Building awesome SDKs for your APIs: Best Practices

Transcript

1. Building awesome SDKs for your APIs: Best Practices Alvaro Navarro 22 March 2021
2. 93% *State of Developer Relations 2020 (Hoopy) https://store.hoopy.io/state-of-devrel-2020
5. Alvaro Navarro Developer Advocate
6. Motivation
7. Motivation Fast and easy adoption of our APIs Better Developer Experience Software Development Kit
8. Motivation But we can generate the SDK from the API specification...
9. Motivation swagger-codegen generate -i openapi.yaml -l language
10. Motivation - Low quality code - Difficult to customize - Brand image - Faster time to market - Support new languages
11. Motivation How do you select the language? - Know your user profile. - Most popular technologies.
12. Motivation
13. Motivation “ Talk is cheap. Show me the code “ -- Linus Torvalds
14. Aim for simplicity
15. Simplicity “ Start with something small and easy to learn, then iterate “
16. Simplicity
17. Simplicity
18. Simplicity
19. Simplicity What about authorization?
20. Simplicity
21. Simplicity Our SDK will be a wrapper around this core!
22. API mapping
23. API mapping “ The SDK should use namespaced methods to create a match between the API and the SDK “
24. API mapping
25. API mapping
26. API mapping Benefits: - Consistency when working with new endpoints. - Avoid potential conflicts.
27. API mapping
28. Error handling
29. Error handling “ Provide custom exceptions (or errors) with useful meaning behind “
30. Error handling
31. Error handling
32. Error handling “ The SDK should raise an error for any request that did not result a HTTP 200 or 201 response code “
33. Reporting
34. Reporting “ The SDK must identify requests to the API as originating from the SDK “
35. Reporting - Monitor level of adoption of the SDK. - Identify usage patterns.
36. Reporting
37. Support logging
38. Logging “ Logging capabilities shall help contributors and users to debug the SDK “
39. Logging
40. Logging
41. Minimum dependencies
42. Dependencies “ If possible, use the minimum needed third-party libraries in the SDK “
43. Dependencies Standard libraries come with built-in for: - Encode/Decode JSON request/responses - http library
44. Dependencies urllib vs requests
45. Dependencies
46. Dependencies Once upon a time...
47. Dependencies
48. Dependencies “ But it is okay to have dependencies for testing “
49. Dependencies
50. Document
51. Document “ Don’t forget to work on the Developer Experience of your SDK “
52. Document
53. Document
54. Document
55. Document
56. Testing
57. Testing “ The SDKs must be thoroughly tested “
58. Testing
59. Testing
60. Testing - Functional tests: API calls + mock server
61. Testing github.com/friendsofgo/killgrave
62. Deploy and Release
63. Release “ The SDK must use CI services to run tests and deploy using the official package managers “
64. Deploy
65. Deploy
66. Write the specification
67. Write the specification “ Write a common specification for all your SDKs “
68. Write the specification MoSCoW method MUST - requirements that should not be deviated from at any cost. SHOULD - requirements that could be deviated from if needed. COULD - requirements that are desirable but not necessary.
69. Write the specification
70. Write the specification
71. Write the specification
72. Write the specification
73. Write the specification
74. Write the specification
75. Conclusions
76. Conclusions - Having good SDKs is key for your API program but it is costly. - Define a common standard for your SDKs. - Start with something small without dependencies. - Pay attention to the Developer Experience.
77. Thanks! alnacle alnacle