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/

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?