Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Building awesome SDKs for your APIs: Best Practices

Building awesome SDKs for your APIs: Best Practices

Alvaro Navarro

March 22, 2021
Tweet

More Decks by Alvaro Navarro

Other Decks in Programming

Transcript

  1. Building awesome SDKs for your APIs:
    Best Practices
    Alvaro Navarro
    22 March 2021

    View full-size slide

  2. 93%
    *State of Developer Relations 2020 (Hoopy)
    https://store.hoopy.io/state-of-devrel-2020

    View full-size slide

  3. Alvaro Navarro
    Developer Advocate

    View full-size slide

  4. Motivation
    Fast and easy adoption of our APIs
    Better Developer Experience
    Software Development Kit

    View full-size slide

  5. Motivation
    But we can generate the SDK from the API
    specification...

    View full-size slide

  6. Motivation
    swagger-codegen generate -i openapi.yaml -l language

    View full-size slide

  7. Motivation
    - Low quality code
    - Difficult to customize
    - Brand image
    - Faster time to market
    - Support new languages

    View full-size slide

  8. Motivation
    How do you select the language?
    - Know your user profile.
    - Most popular technologies.

    View full-size slide

  9. Motivation
    “ Talk is cheap.
    Show me the code “
    -- Linus Torvalds

    View full-size slide

  10. Aim for simplicity

    View full-size slide

  11. Simplicity
    “ Start with something small and easy to learn,
    then iterate “

    View full-size slide

  12. Simplicity
    What about authorization?

    View full-size slide

  13. Simplicity
    Our SDK will be a wrapper around this core!

    View full-size slide

  14. API mapping
    “ The SDK should use namespaced methods to create a
    match between the API and the SDK “

    View full-size slide

  15. API mapping
    Benefits:
    - Consistency when working with new endpoints.
    - Avoid potential conflicts.

    View full-size slide

  16. Error handling

    View full-size slide

  17. Error handling
    “ Provide custom exceptions (or errors) with useful
    meaning behind “

    View full-size slide

  18. Error handling

    View full-size slide

  19. Error handling

    View full-size slide

  20. Error handling
    “ The SDK should raise an error for any request that
    did not result a HTTP 200 or 201 response code “

    View full-size slide

  21. Reporting
    “ The SDK must identify requests to the API as
    originating from the SDK “

    View full-size slide

  22. Reporting
    - Monitor level of adoption of the SDK.
    - Identify usage patterns.

    View full-size slide

  23. Support logging

    View full-size slide

  24. Logging
    “ Logging capabilities shall help contributors and
    users to debug the SDK “

    View full-size slide

  25. Minimum dependencies

    View full-size slide

  26. Dependencies
    “ If possible, use the minimum needed third-party
    libraries in the SDK “

    View full-size slide

  27. Dependencies
    Standard libraries come with built-in for:
    - Encode/Decode JSON request/responses
    - http library

    View full-size slide

  28. Dependencies
    urllib vs requests

    View full-size slide

  29. Dependencies

    View full-size slide

  30. Dependencies
    Once upon a time...

    View full-size slide

  31. Dependencies

    View full-size slide

  32. Dependencies
    “ But it is okay to have dependencies for testing “

    View full-size slide

  33. Dependencies

    View full-size slide

  34. Document
    “ Don’t forget to work on the Developer Experience
    of your SDK “

    View full-size slide

  35. Testing
    “ The SDKs must be thoroughly tested “

    View full-size slide

  36. Testing
    - Functional tests: API calls + mock server

    View full-size slide

  37. Testing
    github.com/friendsofgo/killgrave

    View full-size slide

  38. Deploy and Release

    View full-size slide

  39. Release
    “ The SDK must use CI services to run tests and
    deploy using the official package managers “

    View full-size slide

  40. Write the specification

    View full-size slide

  41. Write the specification
    “ Write a common specification for all your SDKs “

    View full-size slide

  42. 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.

    View full-size slide

  43. Write the specification

    View full-size slide

  44. Write the specification

    View full-size slide

  45. Write the specification

    View full-size slide

  46. Write the specification

    View full-size slide

  47. Write the specification

    View full-size slide

  48. Write the specification

    View full-size slide

  49. 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.

    View full-size slide

  50. Thanks!
    alnacle
    alnacle

    View full-size slide