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