apidays New York 2023 - OpenAPI Best Practices for Generating SDKs, Sid Maestre, APIMatic

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/

Transcript

1. OpenAPI Bes t Pract ices for generat ing SDKs Sid Maes t re VP Developer Relations @APIMatic
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
13. Converting your definition
14. Validate your definition
16. Pitfall #1 Omitting operation ids
17. /pets: post: tags: - pets summary: Updates a pet in the store with form data description: Updates an existing pet and characteristics parameters: []
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
22. Pitfall #2 Omitting tags from operations
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: []
25. Spectral with standard ruleset • Operations missing tag property (warning)
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
27. Pitfall #3 Poorly written or no descriptions
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
31. Pitfall #4 Defining objects or enums inline
32. public List<PetsResponse> listPets( final Integer limit) throws ApiException, IOException { return prepareListPetsRequest(limit).execute(); } content: application/json: schema: type: array items: type: object properties: id: name: petType:
33. public List<Pet> listPets( final Integer limit) throws ApiException, IOException { return prepareListPetsRequest(limit).execute(); } Define them as reusable components content: application/json: schema: $ref: '#/components/schemas/Pet'
34. Spectral with standard ruleset • None
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
36. Pitfall #5 Forgetting examples
37. The following should have examples • Parameters • Request body • Response content • Schema and schema properties
40. @Test public void testTestUpdatePet() throws Exception { Pet body = ApiHelper.deserialize( "{\"id\":12345,\"name\":\"Indiana\",\"petType\":\"dog\"}", Pet.class); try { controller.updatePet(body); } catch (ApiException e) { // Empty block } assertNotNull("Response is null", httpResponse.getResponse()); assertEquals("Status is not 201", 201, httpResponse.getResponse().getStatusCode());
41. Spectral with standard ruleset • None
42. 10 Traps
43. SDK generators
46. Questions?