This presentation teach how to design a real-world and pragmatic web API. It draws from the experience Mario Cardinal have gained over the years being involved architecting many Web API. This presentation begins by differencing between a Web and a REST API, and then continue with the design process. We conclude with the core learnings of the session which is a review of the best practices when designing a web API. Armed with skills acquired, you can expect to see significant improvements in your ability to design a pragmatic web API.

1. Best Practices for Architecting
a Pragmatic Web API
Mario Cardinal
Agile Coach & Software Architect
www.mariocardinal.com
@mario_cardinal
October 15

2. Who am I?
• Agile Coach & Software architect
• Co-Founder of Slingboards Lab
• http://mariocardinal.com

3. 3
Content
1. REST – What is it?
2. RESTful or Resource APIs?
3. Resource APIs or Web APIs?
4. Web APIs – Best practices

4. Application Programming Interface (API)
 A Web API is a software intermediary that makes
it possible for application programs to interact
with each other and share data.
 Often an implementation of REST that exposes a
specific software functionality.
 Simple, intuitive and consistent.
 Friendly to the developer.
 Explorable via HTTP tool.
4
API

5. REST – What is it?
 An architectural style (extends client-server)
introduced by Roy Fielding
 Defines a set of constraints influenced from
the architecture of the Web
 URLs represent resources
 Clients interact with resources via a uniform
interface
 Messages are self-descriptive (ContentType)
 Services are stateless
 Hypermedia (i.e. href tags) drive application state5

6. A more lightweight way to build
services (API)
 Using URLs to build on Web experience
 http://myservice.com/api/resources
 http://myservice.com/api/resources/{id}
 http://myservice.com/api/resources/{id}/relation
 HTTP verbs
 GET, POST, PUT, PATCH, DELETE
 Manage errors at the transport level
6

7. Uniform Interfaces (HTTP Verbs)
GET
POST
PUT
PATCH Updates an existing resource (partially)
DELETE
Retrieves a resource
Guaranteed not to cause side-effects (SAFE)
Results are cacheable
Creates a new resource (process state)
Unsafe: effect of this verb isn’t defined by HTTP
Updates an existing resource
Used for resource creation when client knows URI
Can call N times, same thing will always happen (idempotent)
Can call N times, same thing will always happen (idempotent)
Removes a resource
Can call N times, same thing will always happen (idempotent)

8. Resources come from the business
domain
 Task Board
Sticky Notes
8

9. Resources are nouns
 http://myservice.com/api/stickyNotes
 Verb: GET
 Action: Retrieves a list of sticky notes
 http://myservice.com/api/stickyNotes/12
 Verb: GET
 Action: Retrieves a specific sticky note
 http://myservice.com/api/stickyNotes
 Verb: POST
 Action: Creates a new sticky note
9

10. Resources are nouns
 http://myservice.com/api/stickyNotes/12
 Verb: PUT
 Action: Updates sticky notes #12
 http://myservice.com/api/stickyNotes/12
 Verb: PATCH
 Action: Partially updates sticky note #12
 http://myservice.com/api/stickyNotes/12
 Verb: DELETE
 Action: Deletes sticky note #12
10

11. Most so-called
RESTful APIs are not
RESTful at all
and that’s not a bad thing at all

12. Rather, most “RESTful APIs” are really
“Resource APIs”
http://ServiceDesignPatterns.com/WebServiceAPIStyles/ResourceAPI
again, not a bad thing at all.
Resource APIs totally rock !!!

13. REST Constraint Resource
APIs
Client/Server Yes
Stateless Not required
Cacheable Responses Not required
(Generic) Uniform Interface Yes
Unique URIs Yes
Resources manipulated through Representations Yes
Hypermedia as the Engine of
Application State
Not required
Copyright © 2012 Rob Daigneau, All rights reserved

14. Stateless and cacheable response
 Resource APIs allow the use of cookies
 Cookies create session state that are partly store
on the client (user identification) and on the server
(the state).
 Any response with a Set-Cookie header force the client
to send the cookie in every subsequent HTTP request
 Cookies interfere with cacheable response
 Any response with a Set-Cookie header should not be
cached, at least not the headers, since this can
interfere with user identification and create security
problems 14

15. Hypermedia constraint
 Hypermedia as the Engine of Application
State (HATEOAS)
 Hypermedia constraint states that interaction with
an endpoint should be defined within metadata
returned with the output (URL)
 Apply state transitions (at run time) by following
links
 Resource APIs allow URL to be known when
code is written, and not discover at run time
15

16. Most so-called Web APIs
are Resource APIs
http://en.wikipedia.org/wiki/Web_API
again, not a bad thing at all.
Web APIs totally rock !!!

17. 17
Web APIs – Best practices
1. URL EndPoint
 Resources
 Version
2. Message Body
 Content-Type
3. Error handling
 HTTP Status Code
4. Security
5. Documentation

18. URL identifies a resource
 Endpoint name should be plural
 stickyNotes, collaborators
 Do not forget relations (business domain)
 GET /api/stickynotes/12/collaborators - Retrieves list of
collaborators for sticky note #12
 GET /api/stickynotes/12/collaborators/5 - Retrieves
collaborator #5 for sticky note #12
 POST /api/stickynotes/12/collaborators - Creates a new
collaborator in sticky note #12
 PUT /api/stickynotes/12/collaborators/5 - Updates
collaborator #5 for sticky note #12 18

19. Verbs (actions) as resources
 Actions that don't fit into the world of CRUD
operations can be endpoint
 Change state with ToDo, InProgress or Done
action
 Mark a sticky note in progress with PUT
/stikyNotes/:id/inProgress
 GitHub's API
 star a gist with PUT /gists/:id/star
 unstar with DELETE /gists/:id/star
19

20. Use Query to simplify resources
 Keep the base resource URLs lean by
implementing query parameters on top of the
base URL
 Result filtering, sorting & searching
 GET /api/stickyNotes?q=return&state=ToDo&sort=-
priority,created_at
 Limiting which fields are returned by the API
 GET
/api/stickyNotes?fields=id,subject,state,collaborator,up
dated_at&state=InProgress&sort=-updated_at
20

21. Paginate using link headers
 Return a set of ready-made links so the API
consumer doesn't have to construct links
themselves
 The right way to include pagination details
today is using the ‘Link header’ introduced by
RFC 5988
21
Link header:
<https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
<https://api.github.com/user/repos?page=50&per_page=100>; rel="last"

22. Versioning
 Version via the URL, not via headers
 http://api.myservice.com/v1/stickynotes
 http://myservice.com/v1/stickynotes
 Benefits
 Simple implementation
 Ensure browser explorability
 Issues
 URL representing a resource is NOT stable across
versions 22

23. Message (Content-type)
 JavaScript Object Notation (JSON) is the
preferred resource representation
 It is lighter than XML but as easy for humans to
read and write
 No parsing is needed with JavaScript clients
 Requiring Content-Type JSON
 POST, PUT & PATCH requests should also
require the Content-Type header be set to
application/json or throw a 415 Unsupported
Media Type HTTP status code 23

24. Message (Content-type)
 A JSON object is an unordered set of
name/value pairs
 Squiggly brackets act as 'containers'
 Square brackets holds arrays
 Names and values are separated by a colon.
 Array elements are separated by commas
24
var myJSONObject =
{ "web":[ { "name": "html", "years": "5" },
{ "name": "css", "years": "3" }]
"db":[ { "name": "sql", "years": "7" }]
}

25. Message (Content-type)
 camelCase for field names
 Follow JavaScript naming conventions
 Do not pretty print by default
 Gzip by default
 Gzipping provided over 60% in bandwidth savings
 Always set the Accept-Encoding header
25
{“customerData" : {"id" : 123, "name" : "John" }}
Header:
Accept-Encoding: gzip

26. Message (Post, Put and Patch)
 Updates & creation should return a resource
representation
 To prevent an API consumer from having to hit the
API again for an updated representation, have the
API return the updated (or created) representation
as part of the response
 In case of a POST that resulted in a creation, use
a HTTP 201 status code and include a Location
header that points to the URL of the new resource
26

27. HTTP caching header
 Time-based (Last-Modified)
 When generating a request, include a HTTP
header Last-Modified
 if an inbound HTTP requests contains a If-
Modified-Since header, the API should return a
304 Not Modified status code instead of the output
representation of the resource
 Content-based (ETag)
 This tag is useful when the last modified date is
difficult to determine
27

28. HTTP Rate limiting header
 Include the following headers (using Twitter's
naming conventions as headers typically don't
have mid-word capitalization):
 X-Rate-Limit-Limit - The number of allowed
requests in the current period
 X-Rate-Limit-Remaining - The number of
remaining requests in the current period
 X-Rate-Limit-Reset - The number of seconds left
in the current period
28

29. HTTP status codes
 200 OK - Response to a successful GET, PUT, PATCH or
DELETE. Can also be used for a POST that doesn't result
in a creation.
 201 Created - Response to a POST that results in a
creation. Should be combined with a Location header
pointing to the location of the new resource
 204 No Content - Response to a successful request that
won't be returning a body (like a DELETE request)
 304 Not Modified - Used when HTTP caching headers
are in play
29

30. HTTP status codes
 400 Bad Request - The server cannot or will not process
the request due to something that is perceived to be a
client error
 401 Unauthorized - When no or invalid authentication
details are provided. Also useful to trigger an auth popup
if the API is used from a browser
 403 Forbidden - When authentication succeeded but
authenticated user doesn't have access to the resource
 404 Not Found - When a non-existent resource is
requested
 405 Method Not Allowed - When an HTTP method isn't
allowed for the authenticated user 30

31. HTTP status codes
 409 Conflict - The request could not be completed due to
a conflict with the current state of the resource
 410 Gone - Indicates that the resource at this end point is
no longer available. Useful as a blanket response for old
API versions
 415 Unsupported Media Type - If incorrect content type
was provided as part of the request
 422 Unprocessable Entity - Used for validation errors
 429 Too Many Requests - When a request is rejected due
to rate limiting
31

32. Security
 Encryption
 HTTPS (TLS) everywhere - all the time
32

33. Security
 Authentication
 Never encode authentication on the URI
 Always identify the caller in the HTTP header
 Each request should come with authentication
credentials
 Basic authentication over HTTPS
33

34. Basic authentication over HTTPS
 Create a string with username and password
in the form ”username:password”
 Convert that string to a base64 encoded string
 Prepend the word “Basic” and a space to that
base64 encoded string
 Set the HTTP request’s Authorization header
with the resulting string
34
Header:
Authorization: Basic anNtaXRoOlBvcGNvcm4=

35. Security
 Autorization
 Return HTTP 403 Status Code if not authorized
 If necessity, use the body to provide more info
35
HTTP/1.1
403
Forbidden
Content-Type: application/json; charset=utf-8
Server: Microsoft-IIS/7.0
Date: Sat, 14 Jan 2012 04:00:08 GMT
Content-Length: 251
{
“code" : 123,
“description" : "You are not allowed to read this resource"
}

36. Documentation
 An API is only as good as its documentation
 Docs should be easy to find
 http://myservice.com/api/help
 Docs should show examples of complete
request/response cycles
 Docs should provide error code
 HTTP 4xx and 5xx Status Code
 Error Code for HTTP 409 Status Code
 The holy grail for Web API is an auto-generated,
always up-to-date, stylish documentation 36

37. Documentation
37
URI https://mysite.com:3911/api/members/{id}
HTTP verb PUT
Parameters id : Card number of the member.
Body
name : Name of the member.
email : Email adress of the member.
langage : Langage used by member (Fr_CA ou En_US)
Sample body
{
"name":"Mario Cardinal",
"email":“mcardinal@mariocardinal.com",
"language":"fr_CA"
}
Success
Response
Status Code: 204 No Content
Error Response
Status Code: 400 Bad Request, Body: {"Error Code":"..."}
Status Code: 401 Unauthenticated, see WWW-Authenticate value in header
Status Code: 403 Forbidden
Status Code: 404 Not Found
Status Code: 429 Too Many Requests, see Retry-After value in header
Status Code: 500 Internal Server Error
Status Code: 503 Service Unavailable
Error Code
10: Inactive member
20: Denied access member
110: Database issues, Retry later

38. 38
Do not hesitate to contact me
mcardinal@mariocardinal.com
@mario_cardinal
Q & A