Creating Solid APIs - PyCon Estonia 2018

Presented at PyCon Estonia 2018

Creating APIs that other developers love to use isn't trivial. I'll share some tips and best practices.

See also: https://rivolaks.com/posts/creating-solid-apis/

Transcript

1. Creating Solid APIs
   PyCon Estonia 2018
   Rivo Laks ⋅ 2018-10-04
   

   View Slide

2. Background
   

   View Slide

3. What is an API?
   

   View Slide

4. What is an API?
   application programming interface
   

   View Slide

5. What is an API?
   application programming interface
   application programmer interface
   

   View Slide

6. What is an API?
   application programming interface
   application programmer interface
   API is user interface for developers
   

   View Slide

7. Goals
   

   View Slide

8. Goals
   

   View Slide

9. Goals
   Comprehensive API for 3rd-party devs
   

   View Slide

10. Goals
    Comprehensive API for 3rd-party devs
    Easy & automated onboarding
    

    View Slide

11. Goals
    Comprehensive API for 3rd-party devs
    Easy & automated onboarding
    Minimize pain (friction)
    

    View Slide

12. Versioning
    

    View Slide

13. Why Do We Need Versioning?
    

    View Slide

14. Why Do We Need Versioning?
    for breaking things
    in controlled fashion
    

    View Slide

15. How to Version?
    

    View Slide

16. How to Version?
    You need:
    Deprecation schedules
    

    View Slide

17. How to Version?
    You need:
    Deprecation schedules
    Changelogs / upgrade notes
    

    View Slide

18. Versioning Schemes
    

    View Slide

19. Versioning Schemes
    Using Accept header
    GET /projects HTTP/1.0
    Accept: application/json; version=1
    

    View Slide

20. Versioning Schemes
    Using Accept header
    GET /projects HTTP/1.0
    Accept: application/json; version=1
    Using URL path
    GET /v1/projects HTTP/1.0
    Accept: application/json
    

    View Slide

21. Versioning Schemes Cont.
    Integers ( v1 ) vs dates ( 2018-10-04 )?
    

    View Slide

22. Versioning Schemes Cont.
    Integers ( v1 ) vs dates ( 2018-10-04 )?
    Dates are less emotional
    

    View Slide

23. Versioning Schemes Cont.
    Integers ( v1 ) vs dates ( 2018-10-04 )?
    Dates are less emotional
    Easier internal / test versions
    

    View Slide

24. Version Transformers
    

    View Slide

25. Version Transformers
    » » Requests into newer version » »
    Core code is for latest version
    « « Responses into older version « «
    

    View Slide

26. Version Transformers
    » » Requests into newer version » »
    Core code is for latest version
    « « Responses into older version « «
    Won't work for big, breaking changes
    

    View Slide

27. Authentication &
    Authorization
    

    View Slide

28. Token Authentication
    Clients send HTTP header, ala
    Authorization: Token 9944b09199c62bcf9418
    

    View Slide

29. OAuth 2.0
    

    View Slide

30. OAuth 2.0
    For creating platforms
    

    View Slide

31. OAuth 2.0
    For creating platforms
    Complex, but solves many issues
    

    View Slide

32. OAuth 2.0
    For creating platforms
    Complex, but solves many issues
    Many packages, e.g. Django OAuth Toolkit,
    OAuthLib
    

    View Slide

33. Standardize!
    

    View Slide

34. Standardize!
    Standards help:
    bring familiarity
    

    View Slide

35. Standardize!
    Standards help:
    bring familiarity
    avoid common pitfalls
    

    View Slide

36. Standardize!
    Standards help:
    bring familiarity
    avoid common pitfalls
    historically, standardized approaches win
    

    View Slide

37. JSON API
    http://jsonapi.org/
    one potential standard to use
    

    View Slide

38. JSON API
    http://jsonapi.org/
    one potential standard to use
    GraphQL is another option
    

    View Slide

39. Standardize Structure
    

    View Slide

40. Standardize Structure
    Responses have predictable, familiar
    structure
    

    View Slide

41. GET https://example.com/api/v1/projects
    {
    "links": {
    "next": "https://example.com/api/v1/projects?cursor=cD0yMDE4L",
    "prev": null
    },
    "data": [...],
    "included": [...]
    }
    

    View Slide

42. "data": [
    {
    "type": "project",
    "id": "289",
    "links": {
    "self": "https://example.com/api/v1/projects/289"
    },
    "attributes": {
    "created": "2018-06-28T22:52:08.690486Z",
    "name": "Allison-Patterson",
    "description": "aggregate collaborative models"
    },
    "relationships": {...}
    },
    ...
    ],
    

    View Slide

43. "data": [{ ...
    "relationships": {
    "created_by": {
    "data": {
    "type": "user",
    "id": "199"
    }
    },
    "epics": {
    "data": [
    {
    "type": "epic",
    "id": "3101"
    }
    ],
    }
    } }, ...
    ],
    

    View Slide

44. "included": [
    {
    "type": "epic",
    "id": "3101",
    "attributes": {
    "created": "2018-06-28T22:50:45.885691Z",
    "name": "Ergonomic background extranet"
    },
    "links": {
    "self": "https://example.com/api/v1/epics/3101"
    }
    },
    {
    "type": "user",
    "id": "199",
    "attributes": {...}
    }
    ]
    

    View Slide

45. Impressions?
    

    View Slide

46. Flexibility
    Con gurable elds:
    GET https://example.com/api/v1/projects
    GET https://example.com/api/v1/projects \
    ?included=comments
    GET https://example.com/api/v1/projects \
    ?included=comments&fields[project]=name,comments
    

    View Slide

47. Errors
    

    View Slide

48. Errors
    POST https://example.com/api/v1/projects
    {
    "errors": [
    {
    "title": "Invalid Attribute",
    "detail": "Name must contain at least three letters.",
    "source": { "pointer": "/data/attributes/name" },
    "code": "name_too_short",
    "status": "422"
    }
    ]
    }
    

    View Slide

49. Standardization Matters
    the speci c standard isn't that important
    GraphQL, etc are also good options
    

    View Slide

50. Documentation
    

    View Slide

51. Documentation
    Often overlooked
    

    View Slide

52. Documentation
    Often overlooked
    Gives the rst impression
    

    View Slide

53. Documentation
    Often overlooked
    Gives the rst impression
    The e ort is worth it!
    

    View Slide

54. Creating
    Awesome Docs
    

    View Slide

55. What Should Go In There?
    

    View Slide

56. What Should Go In There?
    The purpose
    

    View Slide

57. What Should Go In There?
    The purpose
    How do I access it?
    

    View Slide

58. What Should Go In There?
    The purpose
    How do I access it?
    Do I need developer account?
    

    View Slide

59. What Should Go In There?
    The purpose
    How do I access it?
    Do I need developer account?
    Root URL, etc
    

    View Slide

60. What Should Go In There?
    The purpose
    How do I access it?
    Do I need developer account?
    Root URL, etc
    Authentication info
    

    View Slide

61. What Should Go In There?
    General encodings, formats, etc
    

    View Slide

62. What Should Go In There?
    General encodings, formats, etc
    Versioning, pagination, etc
    

    View Slide

63. What Should Go In There?
    General encodings, formats, etc
    Versioning, pagination, etc
    Common errors
    

    View Slide

64. What Should Go In There?
    General encodings, formats, etc
    Versioning, pagination, etc
    Common errors
    Code for getting started
    

    View Slide

65. The Endpoints
    

    View Slide

66. The Endpoints
    URL & operations
    

    View Slide

67. The Endpoints
    URL & operations
    Request/response data
    

    View Slide

68. The Endpoints
    URL & operations
    Request/response data
    Optional parameters
    

    View Slide

69. The Endpoints
    URL & operations
    Request/response data
    Optional parameters
    Permissions etc
    

    View Slide

70. Keep it Fresh!
    

    View Slide

71. Keep it Fresh!
    Obsolete docs are the worst
    

    View Slide

72. Keep it Fresh!
    Obsolete docs are the worst
    Always autogenerate!
    

    View Slide

73. Keep it Fresh!
    Obsolete docs are the worst
    Always autogenerate!
    Usually code » schema » docs
    

    View Slide

74. Schema & Autogeneration
    

    View Slide

75. Schema & Autogeneration
    OpenAPI, Swagger, etc
    

    View Slide

76. Schema & Autogeneration
    OpenAPI, Swagger, etc
    Use your tools
    

    View Slide

77. Schema & Autogeneration
    OpenAPI, Swagger, etc
    Use your tools
    Combine docs & code examples
    

    View Slide

78. Schema & Autogeneration
    OpenAPI, Swagger, etc
    Use your tools
    Combine docs & code examples
    Client libs autogeneration
    

    View Slide

79. In Summary
    Embrace standards (e.g. JSON API)
    Invest in documentation
    Use automation
    Reduce friction
    

    View Slide

80. Thanks!
    Rivo Laks ⋅ @rivolaks ⋅ rivolaks.com
    tinyurl.com/PyConEstonia18api
    

    View Slide