Design principles of RESTful applications

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

Transcript

1. Design principles of RESTful applications Youwe PHP Meet-Ups 2017 - Osman Ungur
2. 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
3. Topics • Principles and essentials • Implementation problems • Architectural problems • Fallacies of distributed computing • Logging and monitoring
4. Distributed Architectures • Service-Oriented Architectures (SOAP) • Resource-Oriented Architectures (RESTful) • Microservices (RESTish)
5. Distributed Architectures • Service-Oriented Architectures (SOAP) • Resource-Oriented Architectures (RESTful) • Microservices (RESTish)
6. Principles
7. 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
8. 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
9. Caching • Clients can cache responses • Responses implicitly or explicitly, define themselves as cacheable • Well-managed caching partially or completely eliminates some client–server interactions
10. Simplicity of interfaces • Stateless interactions • Uniform interfaces and easy to understand data representations • Standard HTTP methods (GET, PUT, POST, or DELETE)
11. API is a user interface for developers • Keep simple • Consistent and intuitive • Good documented
12. API is a user interface for developers • Keep simple • Consistent and intuitive • Good documented
14. URL design Plural nouns not verbs
15. URL Design Don’t /getUsers /createUser /verifyEmail /updateComment
16. URL Design Don’t GET /users-1 GET /users/1/comments-10
17. URL Design Don’t GET /users?id=1 GET /users?id=1&comments=10 GET /api?resource=users&id=1 GET /api?object=users&do=delete&id=1
19. URL Design Collection resource GET /users Instance resource GET /users/1 Sub-resources GET /users/1/comments/10
20. URL design GET /it-looks/more-readable Don't POST api.domain.com/accessTokens Do POST api.domain.com/access-tokens
21. URL design Combining multiple resources is bad Don't GET /homepage Do GET /news/latest GET /news/featured GET /blog/posts/?limit=10
22. 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”
24. Methods POST Create a resource within a given collection GET Retrieve a resource PUT / PATCH Update a resource DELETE Delete a resource
25. 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
26. 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
27. URL examples Aliases for common queries GET /comments/needs_moderation POST /users/1/promote
28. 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
29. Base URL Don't domain.com/api/prod Do api.domain.com
30. Versioning Don’t Header: application/json;app&v=1 Do api.domain.com/v1
31. 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
33. 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.
34. 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
35. Use only JSON (if possible) • Human readable • Easy to create • Easy to parse
36. Use only JSON (if possible) • Dont invent yet another data format • Avoid language-specific data interchange formats • XML sucks :(
37. 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
38. Authentication Don’t GET /users/1/comments?apiKey=Dahxach7 DELETE /users/1/comments/10? apiKey=ea5eaGa2&username=crayz_boy_17_m &password=letmein
40. 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.
41. Authentication • Seperate user roles • Use ACL for accessing and modifying resources • Prevent modifying resource not belong to user
42. HTTP caching HTTP provides a built-in caching framework with headers!
43. 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.
44. 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.
45. Caching • Use shared cache layer (e.g. Memcached, Redis) • Choose right expire time • Evict or update if objects changed • Keep MISS rate low
46. Caching • Improves performance • Minimizes database queries • Databases - mostly - slower than cache solutions • Minimizes HTTP request roundtrips
47. 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)
48. Framework capabilities • Marshalling • Validation • Secure access to datasources • Exception handling (and stacktraces on development mode)
49. Errors • Developers are your customers • As much information as possible • As descriptive as possible • "500 - An error occured." is bad
50. 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
51. 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
52. 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.
53. Documentation • Document every convention about project. • Code review is a must. • Use git and gitflow. • Write tests as much as possible.
54. Fallacies • The network is reliable • Latency is zero • Bandwidth is infinite
55. Fallacies • The network is secure • Topology doesn't change • There is one administrator
56. Fallacies • Transport cost is zero • The network is homogeneous
57. Failures • Use load-balancing for application servers • Keep backup servers for disasters • Use master-slave topology for datasources
58. Automation Automate everything as much as possible • Deploys • Builds • Provisioning
59. Logging Example tools • Syslog-ng • Graylog2 • Logstash
60. Logging • Exception logs written by framework • Web-server access and error logs • Other technologies used in project
61. Monitoring Infrastructure • Monitor application servers performance constantly • Use alerting systems for catastrophic failures • Pay attention to high load, memory and disk usage
62. Monitoring Application • Monitor response times, memory usage • Performance per route • Exceptions
63. Thanks! github.com/o