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

5538316cd7917cae8241cc4e6d481ad6?s=128

Alvaro Navarro

March 22, 2021
Tweet

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

  3. None
  4. None
  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