The never ending REST API design debate -- Devoxx France 2016

Transcript

1. DES VEAUX.FR
   $KGPXGPWG¢
   

   View Slide

2. View Slide

3. 2
   Je suis Charlie,
   Je suis Paris,
   Je suis Bruxelles…
   

   View Slide

4. 2
   Je suis Charlie,
   Je suis Paris,
   Je suis Bruxelles…
   Les français sont
   des veaux !
   

   View Slide

5. View Slide

6. Google Vision API
   

   View Slide

7. Google Vision API
   

   View Slide

8. Google Vision API
   

   View Slide

9. Google Vision API
   J’aime les
   micro-
   services
   

   View Slide

10. Google Vision API
    J’aime les
    micro-
    services
    Maintenant,
    on va parler
    du RESTe…
    

    View Slide

11. The never-ending REST
    API design debate
    Guillaume Laforge
    Restlet — the Web API platform
    Chair of the Apache Groovy PMC
    @glaforge
    

    View Slide

12. View Slide

13. Devoxx Promo Code: ctwdevoxxfr
    http://www.manning.com/koenig2/
    GROOVY
    IN ACTION
    2ND EDITION
    

    View Slide

14. We know
    about
    APIs!
    http://restlet.com
    

    View Slide

15. We know
    about
    APIs!
    http://restlet.com
    

    View Slide

16. ROY FIELDING
    REST
    DISSERTATION
    

    View Slide

17. ROY FIELDING
    REST
    DISSERTATION
    Principled design
    of the modern
    Web architecture
    

    View Slide

18. 8
    Representational State Transfer
    Architectural properties
    • Performance
    • Scalability
    • Simplicity
    • Modifiability
    • Visibility
    • Portability
    • Reliability
    Architectural constraints
    • Client-server
    • Stateless
    • Cacheable
    • Layered system
    • Code on demand (optional)
    • Uniform interface
    

    View Slide

19. 9
    REST — Uniform interface
    • Identification of resources
    • Manipulation of resources 

    through representations
    • Self-descriptive messages
    • HATEOAS 

    (Hypermedia As The Engine 

    Of Application State)
    

    View Slide

20. 9
    REST — Uniform interface
    • Identification of resources
    • Manipulation of resources 

    through representations
    • Self-descriptive messages
    • HATEOAS 

    (Hypermedia As The Engine 

    Of Application State)
    Resource as URIs
    http://api.co/cars/123
    

    View Slide

21. 9
    REST — Uniform interface
    • Identification of resources
    • Manipulation of resources 

    through representations
    • Self-descriptive messages
    • HATEOAS 

    (Hypermedia As The Engine 

    Of Application State)
    Resource as URIs
    http://api.co/cars/123
    JSON, XML…
    

    View Slide

22. 9
    REST — Uniform interface
    • Identification of resources
    • Manipulation of resources 

    through representations
    • Self-descriptive messages
    • HATEOAS 

    (Hypermedia As The Engine 

    Of Application State)
    Resource as URIs
    http://api.co/cars/123
    JSON, XML…
    HTTP GET, POST, PUT, DELETE
    media types, cacheability…
    

    View Slide

23. 9
    REST — Uniform interface
    • Identification of resources
    • Manipulation of resources 

    through representations
    • Self-descriptive messages
    • HATEOAS 

    (Hypermedia As The Engine 

    Of Application State)
    Resource as URIs
    http://api.co/cars/123
    JSON, XML…
    HTTP GET, POST, PUT, DELETE
    media types, cacheability…
    Hypermedia APIs
    HAL, JSON-LD, Siren…
    

    View Slide

24. 10
    HTTP methods / URIs for collection/item
    GET
    POST
    PUT
    DELETE
    http://api.co/v2/cars/ http://api.co/v2/cars/1234
    List all the cars Retrieve an individual car
    Create a new car Error
    Replace the entire collection
    with a whole new list of cars
    Update an individual car
    Delete all the cars Delete an individual car
    

    View Slide

25. NOUNS
    ARE GOOD
    VERBS
    ARE BAD
    

    View Slide

26. 12
    Nouns are good, verbs are bad!
    • Prefer nouns to verbs
    • nouns refer to resources
    • resources are handled with HTTP verbs
    • Verbs can be used for actions or calculations
    • /login, /logout
    • /convertTemperature
    • /repositories/123/star
    

    View Slide

27. View Slide

28. 14
    Singular or plural resources?
    • Prefer plural forms
    • /tickets/234 vs /ticket/234
    • Avoid confusing odd singular vs plural forms
    • /person vs /people, or /goose vs /geese
    • Easier for URL routing (same prefix)
    • Think of it as: 

    ‘This is the 234th item of the tickets collection’
    

    View Slide

29. Camel
    case?
    

    View Slide

30. Camel
    case?
    Snake
    case!
    

    View Slide

31. 16
    Different casing in the wild
    • UpperCamelCase or lowerCamelCase
    • snake_case or dashed-snake-case
    • Prefer lowercase
    • Prefer snake_case
    • Underscores seem more common in APIs
    • But chose one casing and be consistent!
    

    View Slide

32. 17
    Dealing with relations in your URLs
    • /tickets/123/messages/4
    • a ticket could be a group of messages
    • /usergroups/234/users/67
    • a user could belong to different usergroups
    • user should have a URL of its own, referenced from the
    usergroup payload
    

    View Slide

33. API PARAMETERS
    RULE OF THUMBS
    

    View Slide

34. 19
    API parameters — rule of thumbs
    • Path
    • required, resource identifier
    • Query
    • optional, query collections
    • Body
    • resource specific logic
    • Header
    • global, platform-wide
    

    View Slide

35. 20
    HTTP Status Code Map http://bit.ly/stcode
    

    View Slide

36. 21
    Common HTTP status codes
    • Use appropriate HTTP status codes when answering
    requests:
    • 1xx: Hold on…
    • 2xx: Here you go!
    • 3xx: Go away!
    • 4xx: You fucked up :-D
    • 5xx: I fucked up :-(
    

    View Slide

37. 22
    Common HTTP Status Codes — 1xx
    

    View Slide

38. 23
    Common HTTP Status Codes — 2xx
    

    View Slide

39. 23
    Common HTTP Status Codes — 2xx
    

    View Slide

40. 23
    Common HTTP Status Codes — 2xx
    

    View Slide

41. 23
    Common HTTP Status Codes — 2xx
    

    View Slide

42. 23
    Common HTTP Status Codes — 2xx
    

    View Slide

43. 23
    Common HTTP Status Codes — 2xx
    

    View Slide

44. NOT
    JUST
    200
    201
    202
    204
    206
    

    View Slide

45. Anti-pattern:
    returns 200
    for everything,
    even errors!
    

    View Slide

46. 26
    Not just 200 OK! — 201 Created
    • Specify a Location header, pointing at the location of the
    newly created resource
    POST /cars ...
    HTTP/1.1 201 Created
    Location: http://cars.co/v2/cars/5959
    

    View Slide

47. API navigation is
    important to make the
    API more discoverable
    

    View Slide

48. 28
    DHC by Restlet: API testing tool
    

    View Slide

49. 29
    Not just 200 OK! — 202 Accepted
    • Request accepted but will be handled asynchronously
    • a job might be running later and yield a result later on
    POST /jobs ...
    HTTP/1.1 202 Accepted
    No payload
    returned
    

    View Slide

50. 30
    Not just 200 OK! — 204 No content
    • The resource was deleted and no payload is returned
    • but could return 200 OK 

    & provide the payload of the deleted element
    DELETE /tickets/654
    HTTP/1.1 204 No content
    

    View Slide

51. 31
    Not just 200 OK! — 206 Partial content
    • A partial list of meteorites is returned, using pagination
    • add a Link header to facilitate navigation
    GET /meteorites?page=4
    HTTP/1.1 206 Partial content
    Link: ; rel="first", 

    ; rel="prev",
    ; rel="next", 

    ; rel="last"
    ...
    

    View Slide

52. 32
    Not just 200 OK! — 304 Not modified
    • When HTTP caching headers are in play
    • the client should have a version in cache already
    GET /meteorites/654
    HTTP/1.1 304 Not modified
    

    View Slide

53. Caching!
    

    View Slide

54. 34
    Last-Modified
    GET /users/123
    Modified-Since: Wed, 13 Apr 2016 02:13:11 GMT
    HTTP/1.1 200 OK
    Last-Modified: Fri, 15 Apr 2016 04:58:08 GMT
    

    View Slide

55. 35
    ETag
    GET /users/123
    If-None-Match: a456ef544eeb7333af
    HTTP/1.1 200 OK
    ETag: 686897696a7c876b7e
    GET /users/123
    If-None-Match: 686897696a7c876b7e
    HTTP/1.1 304 Not modified
    

    View Slide

56. PAGINATION
    

    View Slide

57. 37
    Pagination with query parameters
    • With a page number: ?page=23
    • can also specify a page size
    • might get odd results when insertions happen
    • With a cursor: ?cursor=34ea3fd6
    • insertion-friendly
    • With a semantic parameter: ?page=A
    • interesting when limited / discrete number of pages
    

    View Slide

58. 38
    Pagination with accept range header
    • Accept range header not just for bytes
    GET /users
    HTTP/1.1 206 Partial content
    Accept-Ranges: users
    Content-Range: users 0-9/200
    GET /users
    Range: users=0-9
    

    View Slide

59. Wrapped
    CollectionS
    

    View Slide

60. 40
    Wrapped collections
    • Prefer unwrapped collections
    • unless there’s specific collection payload metadata

    (example: photo album details)
    • pagination are better in HTTP headers
    GET /tickets
    Content-Type: application/json
    {
    data: [
    { id: 1, ... },
    { id: 2, ... }
    ]
    }
    GET /tickets
    Content-Type: application/json
    [
    { id: 1, ... },
    { id: 2, ... }
    ]
    

    View Slide

61. 41
    Common HTTP Status Codes — 3xx
    

    View Slide

62. 41
    Common HTTP Status Codes — 3xx
    

    View Slide

63. 41
    Common HTTP Status Codes — 3xx
    

    View Slide

64. 41
    Common HTTP Status Codes — 3xx
    

    View Slide

65. 41
    Common HTTP Status Codes — 3xx
    

    View Slide

66. 41
    Common HTTP Status Codes — 3xx
    

    View Slide

67. 42
    Common HTTP Status Codes — 4xx
    

    View Slide

68. 42
    Common HTTP Status Codes — 4xx
    

    View Slide

69. 42
    Common HTTP Status Codes — 4xx
    

    View Slide

70. 42
    Common HTTP Status Codes — 4xx
    

    View Slide

71. 42
    Common HTTP Status Codes — 4xx
    

    View Slide

72. 42
    Common HTTP Status Codes — 4xx
    

    View Slide

73. 43
    Provide helpful error payloads
    • No definitive standard yet
    • http problem proposal and vnd-error mime type
    HTTP/1.1 403 Forbidden
    Content-Type: application/problem+json
    Content-Language: en
    {
    "type": "https://example.com/probs/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "Your current balance is 30, but that costs 50.",
    "instance": "/account/12345/msgs/abc",
    "balance": 30,
    "accounts": ["/account/12345", "/account/67890"]
    }
    

    View Slide

74. 44
    Common HTTP Status Codes — 5xx
    

    View Slide

75. 44
    Common HTTP Status Codes — 5xx
    

    View Slide

76. 44
    Common HTTP Status Codes — 5xx
    

    View Slide

77. 44
    Common HTTP Status Codes — 5xx
    

    View Slide

78. 45
    Treating unknown status codes
    • An unknown status code should be treated 

    as the first one of the family
    • 4xx — 400 generic client error
    • 5xx — 500 generic server error
    

    View Slide

79. RATE
    LIMITATION
    

    View Slide

80. 47
    Rate limitation
    HTTP/1.1 200 OK
    Date: Mon, 01 Jul 2013 17:27:06 GMT
    Status: 200 OK
    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 56
    X-RateLimit-Reset: 1372700873
    Total number of
    requests allowed
    Number of
    requests left
    remaining window before
    the rate limit resets in UTC
    epoch seconds
    

    View Slide

81. ONE
    SIZE
    FITS
    ALL
    Different payloads
    for different
    consumers
    

    View Slide

82. 49
    Selecting with query parameters
    • Only 5 stars Chinese restaurants
    • GET https://api.co/restaurants?type=chinese&stars=5
    

    View Slide

83. FIL
    TERING
    

    View Slide

84. 51
    Filtering
    • Specify fields you’re interested in:
    • GET https://api.co/users/123?fields=firstname,lastname,age
    • Specify excluded fields:
    • GET https://api.co/users/123?exclude=biography,resume
    • Specify a « style »:
    • GET https://api.co/users/123?style=compact
    

    View Slide

85. 52
    Prefer… the prefer header
    GET /users/123 HTTP/1.1
    Content-Type: application/json
    Prefer: return=minimal
    Vary: Prefer,Accept,Accept-Encoding
    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Vary: Prefer,Accept,Accept-Encoding
    Preference-Applied: return=minimal
    Define different
    profiles: minimal,
    mobile, full…
    

    View Slide

86. 53
    Expanding referenced resources
    • Use the dot notation to explicit you want sub-resources
    • GET https://api.co/users/123?fields=address.zip
    • user
    • name
    • address
    • zip
    • country
    • …
    • …
    

    View Slide

87. SORTING
    

    View Slide

88. 55
    Sorting
    • SQL-style
    • GET https://api.co/books?sort=title+DESC
    • GET https://api.co/books?sort=title+DESC,author+ASC
    • Sort + asc/desc combo
    • GET https://api.co/books?sort=title&desc=title
    • GET https://api.co/books?
    sort=title,author&desc=title&asc=author
    

    View Slide

89. SEARCHING
    

    View Slide

90. 57
    Searching
    • Combine various filtering fields
    • Or provide a full-blown query language
    

    View Slide

91. 58
    Search / filter / sort…
    • Also have a look at other approaches
    • Facebook’s GraphQL
    • Netflix’s Falcor
    

    View Slide

92. v1
    

    View Slide

93. 60
    Different approaches for API versioning
    • Most frequent, in the URL:
    • https://api.com/v2/restaurants/1234
    • Custom header:
    • X-API-Version: 2
    • Less frequent, with an accept header
    • clients don’t have to change endpoint, but update headers
    GET /restaurants
    Accept: application/vnd.restaurants.v2+json
    

    View Slide

94. hypermedia
    

    View Slide

95. 62
    Richardson maturity model
    

    View Slide

96. 63
    Pros & Cons of hypermedia
    • Pros
    • more generic clients
    • can palliate the need for API versioning
    • Cons
    • heavier payload (think mobile devices w/ bad connectivity)
    • clients still need to understand what links are about and
    how to represent them in their UI
    

    View Slide

97. C
    H
    A
    N
    G
    E
    IS
    U
    N
    A
    V
    O
    ID
    A
    B
    L
    E
    

    View Slide

98. 65
    Lots of choice
    • HAL
    • JSON-LD
    • Collection+JSON
    • SIREN
    • …
    • Which to chose from?
    • no real consensus yet
    • but HAL seems quite common
    

    View Slide

99. 66
    A word about IDs for linked resources
    • If you’re tempted to go your own way for hypermedia…
    • Be sure to define direct links to resources
    • photos: [http://news.co/articles/123/photos/654,

    http://news.co/articles/123/photos/659]
    • Not mere IDs for which API clients need to figure out the
    exact resource location (error-prone)
    • photos: [654, 659]
    

    View Slide

100. 67
     Another word about IDs
     • Usually avoid counter-type IDs: 1, 2, 3, 4…
     • Prefer UUIDs
     • makes it harder for malignant users 

     to scan & discover existing resources
     • auto-incrementing IDs might not be unique 

     in distributed systems
     

     View Slide

101. HAL
     I’m sorry Dave, I
     can do Hypermedia
     

     View Slide

102. 69
     HAL approach
     GET https://api.com/player/1234567890
     HTTP/1.1 200 OK
     {
     "_links": {
     "self": { "href": "https://api.com/player/1234567890" },
     "friends": { "href": "https://api.com/player/1234567890/friends" }
     },
     "playerId": "1234567890",
     "name": "Kevin Sookocheff",
     "alternateName": "soofaloofa",
     "image": "https://api.com/player/1234567890/avatar.png"
     }
     Special _links property
     

     View Slide

103. Resources
     

     View Slide

104. 71
     API design resources
     • http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
     • https://github.com/paypal/api-standards/blob/master/api-style-guide.md
     • http://blog.octo.com/en/design-a-rest-api/
     • https://github.com/interagent/http-api-design/blob/master/SUMMARY.md
     • http://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
     • http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
     

     View Slide

105. Thanks for your attention
     

     View Slide

106. Questions & Answers
     

     View Slide