apidays New York 2023
APIs for Embedded Business Models: Finance, Healthcare, Retail, and Media
May 16 & 17, 2023
OpenAPI Best Practices for Generating SDKs
Sid Maestre, Developer Relations at APIMatic
------
Check out our conferences at https://www.apidays.global/
Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8
Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io
Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/
Call Girls In Mahipalpur O9654467111 Escorts Service
apidays New York 2023 - OpenAPI Best Practices for Generating SDKs, Sid Maestre, APIMatic
1. OpenAPI Bes t Pract ices
for generat ing SDKs
Sid Maes t re
VP Developer Relations @APIMatic
2.
3.
4.
5.
6.
7.
8.
9.
10.
11. Benefits of generated SDKs
● Your API definition is the source of truth
● Updates can be rolled out in multiple SDKs.
● Building SDKs and documentation part of your CI/ CD pipeline.
● Updates are more accurate and less time consuming.
● Focus engineering resources on building new features, not SDKs.
12. 3 ways to create an API definition
Manually Annotation HTTP Traffic
18. … or duplicate operation id
/pets:
post:
operationId: updatePet
summary: Updates a pet in the store with form data
put:
operationId: updatePet
summary: Updates a pet in the store with form data
19. include a unique operation id
/pets:
post:
tags:
- pets
summary: Updates a pet in the store with form data
operationId: updatePet
description: Updates an existing pet and characteristics
parameters: []
20. Spectral with standard ruleset
● Duplicate operationId (error)
● No operation Id (warning)
21. 💡💡 Tips for naming your operationId
● Use name pattern of a verb + object/ resource.
● Aim to be 30 characters or less
● Avoid using stop words like "a", "the" and "and" in the name.
● createPet / updatePet / listPets
23. /pets:
post:
summary: Updates a pet in the store with form data
operationId: updatePet
description: Updates an existing pet and characteristics
parameters: []
24. /pets:
Post:
tags:
- pets
summary: Updates a pet in the store with form data
operationId: updatePet
description: Updates an existing pet and characteristics
parameters: []
26. 💡💡 Tips for naming tags
● Identify the ideal groupings for your methods.
● Pluralize all names unless they are singleton resources.
● Aim to be 30 characters or less
● petsController
28. The following should have descriptions
● Info
● Tag
● Operations and Parameters
● Request body
● Response content
● Schema and schema properties
29. Spectral with standard ruleset
● Response content (error)
● Info (warning)
● Tag (warning)
● Operations (warning) and Parameters
● Request body
● Schema and schema properties
30. 💡💡 Tips for writing good descriptions
● Describe the element and mention any edge cases that may occur
● Avoid short descriptions that don’t add value.
Describe the response from the listPets operation
⛔ description: list response
✅ description: A paged array of pets
35. 💡💡 Tips for naming objects
● Use singular unless it represents some kind of collection of things
● Do not prefix or postfix based on their schema type.
⛔ PetsResponse
⛔ PetObject
✅ Pet