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

Design principles of RESTful applications

Osman
November 02, 2017

Design principles of RESTful applications

Youwe Amsterdam (Experiences about PHP and (S|R)OA Revisited)

Osman

November 02, 2017
Tweet

More Decks by Osman

Other Decks in Technology

Transcript

  1. Who i am? • Software architect with system-administration background over

    10 years • Mostly writes PHP and Java • Also working about infrastructure design, system automation, deployment and monitoring • Obsessed about clean, well structured, maintainable and scalable architectures • Loves open source, `o` at github
  2. Topics • Principles and essentials • Implementation problems • Architectural

    problems • Fallacies of distributed computing • Logging and monitoring
  3. Separation of concerns and portability • Clients are not concerned

    with data storage • Servers are not concerned with the user interface or user state • Servers and clients may also be replaced and developed independently
  4. Scalability and performance • Designing clustered applications with REST interfaces

    is not complicated • Easier to scale, both horizontally and vertically • Load-balancing and proxying is easy
  5. Caching • Clients can cache responses • Responses implicitly or

    explicitly, define themselves as cacheable • Well-managed caching partially or completely eliminates some client–server interactions
  6. Simplicity of interfaces • Stateless interactions • Uniform interfaces and

    easy to understand data representations • Standard HTTP methods (GET, PUT, POST, or DELETE)
  7. API is a user interface for developers • Keep simple

    • Consistent and intuitive • Good documented
  8. API is a user interface for developers • Keep simple

    • Consistent and intuitive • Good documented
  9. URL design Combining multiple resources is bad Don't GET /homepage

    Do GET /news/latest GET /news/featured GET /blog/posts/?limit=10
  10. HTTP Methods Don’t • Tunnelling everything through GET • Resources

    are not identified by URIs, URIs are used to encode operations and their parameters • There is a risk that “crawlers”
  11. Methods POST Create a resource within a given collection GET

    Retrieve a resource PUT / PATCH Update a resource DELETE Delete a resource
  12. URL examples GET /users - Retrieves a list of users

    GET /users/1 - Retrieves a specific user POST /users - Creates a new user PUT /users/1 - Updates user #1 PATCH /users/1 - Partially updates user #1 | /users/1/ lock, /users/1/ban DELETE /users/1 - Deletes user #1
  13. URL examples GET /users/1/comments - Retrieves list of comments for

    user #1 GET /users/1/comments/10 - Retrieves message #10 for user #1 POST /users/1/comments - Creates a new message in user #1 PUT /users/1/comments/10 - Updates message #10 for user #1 PATCH /users/1/comments/10 - Partially updates message #10 for user #1 DELETE /users/1/comments/10 - Deletes message #10 for user #1
  14. URL examples Filtering: GET /users?active=true Sorting: GET /users?sort=-id Limiting: GET

    /users?limit=100&page=3 Field filtering: GET /users? fields=name,surname,email
  15. Status Codes Don't • Only returns 200 (OK) or 500

    (Internal Server Error) • Only returns 200 (OK) with an error message encoded in the response body
  16. Status Codes • HTTP protocol has an extensive set of

    application- level response codes that you can use to describe various results of your API calls. • The API should always return sensible HTTP status codes. API errors typically break down into 2 types: • 400 series status codes for client issues & 500 series status codes for server issues.
  17. 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 • 400 Bad Request - The request is malformed, such as if the body does not parse • 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 is being requested that isn't allowed for the authenticated user • 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
  18. Use only JSON (if possible) • Dont invent yet another

    data format • Avoid language-specific data interchange formats • XML sucks :(
  19. Authentication A RESTful API should be stateless. This means that

    request authentication should not depend on cookies or sessions. Instead, each request should come with some sort authentication credentials. REST: Representational State Transfer
  20. Authentication • Use header based auth. tokens • Seperated for

    API authorisation and user authentication (e.g. oAuth) • 401 Unauthorized and 403 Forbidden response codes for disallow • Store user access tokens in key-value NoSQL solution supports persistance and expire.
  21. Authentication • Seperate user roles • Use ACL for accessing

    and modifying resources • Prevent modifying resource not belong to user
  22. HTTP caching ETag: When generating a request, include a HTTP

    header ETag containing a hash or checksum of the representation. This value should change whenever the output representation changes. Now, if an inbound HTTP requests contains a If-None-Match header with a matching ETag value, the API should return a 304 Not Modified status code instead of the output representation of the resource.
  23. HTTP caching Last-Modified: This basically works like to ETag, except

    that it uses timestamps. The response header Last-Modified contains a timestamp in RFC 1123 format which is validated against If-Modified-Since. Note that the HTTP spec has had 3 different acceptable date formats and the server should be prepared to accept any one of them.
  24. Caching • Use shared cache layer (e.g. Memcached, Redis) •

    Choose right expire time • Evict or update if objects changed • Keep MISS rate low
  25. Caching • Improves performance • Minimizes database queries • Databases

    - mostly - slower than cache solutions • Minimizes HTTP request roundtrips
  26. Mobile first • Deprecate, don't remove immediately • Keep backward

    compatibility in your mind • Use strict signatures for error response • Don't use array keys in PHP (Breaks object mapping in strongly typed languages)
  27. Framework capabilities • Marshalling • Validation • Secure access to

    datasources • Exception handling (and stacktraces on development mode)
  28. Errors • Developers are your customers • As much information

    as possible • As descriptive as possible • "500 - An error occured." is bad
  29. Environments Seperated environments is a must have • Production -

    Stable code uses production datasources • Staging - Stable code uses staging datasources • Development - Development snapshot code uses staging datasources
  30. Environments • Keep your project easy to deploy • Use

    latest libraries and tools for security and performance • Use Docker or Vagrant for development environment • Give daily fresh datasource replicas to developers
  31. Documentation • Document every URI and method • Detailed information

    about parameters, requirements, data types, status codes and default values. • Keep updated and accessible. • Add simple examples with cURL.
  32. Documentation • Document every convention about project. • Code review

    is a must. • Use git and gitflow. • Write tests as much as possible.
  33. Failures • Use load-balancing for application servers • Keep backup

    servers for disasters • Use master-slave topology for datasources
  34. Logging • Exception logs written by framework • Web-server access

    and error logs • Other technologies used in project
  35. Monitoring Infrastructure • Monitor application servers performance constantly • Use

    alerting systems for catastrophic failures • Pay attention to high load, memory and disk usage