Representational State Transfer (REST)

---

##Summary

Representational State Transfer (REST) is a software architecture style that relies on a stateless, client-server, cacheable communications protocol. The idea is that client-server is separated for portability of code and ability to scale web services. REST basically exposes application data through an API and with a web framework like django, it’s easy to use django-rest-framework to implement a RESTful API.

##HTTP Messages

HTTP messages are made up of a header and optionally a body. Messages can be either a:

1. request that sends from client to server
2. response that sends from server to client

HTTP messages are made up of a header and body.

####HTTP Message Header

HTTP Header contains metadata and can only contain plain text formatted in a specific manner. These include:

• general-header
• request-header
• response-header

####HTTP Message Body (optional)

HTTP body can contain any data in any format. You can send plain text, HTML, XML, etc. By requesting different metadata or URLs, you can choose between different representations for the same resource (e.g. send webpage to browsers, JSON to applications).

####HTTP Response

HTTP Response should specify the content type of the body using the Content-Type field. For example: Content/Type: application/json.

##Commands

REST systems communicate over Hypertext Transfer Protocol (https) and uses the following commands to retrieve and send data.

• GET
  • Read an existing resource. This is like SELECT in SQL. This is a ‘SAFE’ method (along with HEAD, OPTIONS) while the others below are considered ‘UNSAFE’ (may modify resource).
• HEAD
  • Similar to GET except server doesn’t return a message-body in response. Instead, it gets only the metadata of an existing resource.
• POST
  • Creates a new resource. This is like INSERT in SQL
• PUT
  • Updates an existing resource. This is like UPDATE in SQL
• PATCH
  • Usually not implemented. Updates part of an existing resource. This is like UPDATE in SQL
• DELETE
  • Deletes an existing resource. This is like DELETE in SQL
• OPTIONS
  • This returns the HTTP methods that the server supports at this specified URL (used for checking functionality of a web server by requesting ‘*’ instead of a specific resource; e.g. * instead of say resource id 2)

##Important HTTP Status Codes

• 200 OK means Success
  • GET returns resource
  • PUT provides status message or returns message
• 201 Created means Success
  • POST provides status message or returns newly created resource
• 204 No Content means Success
  • Completed, but nothing to return (because of no content)
• 304 Unchanged means Redirect
  • There’s no changes since the last request (usually used to checking a field like ‘Last-Modified’ and ‘Etag’ headers, which is a mechanism for web cache validation)
• 400 Bad Request means Failure
  • PUT returns error message, including form validation errors
  • POST returns error message, including form validation errors
• 401 Unauthorized means Failure
  • Authentication required but user did not provide credentials
• 403 Forbidden means Failure
  • User attempted to access restricted content
• 404 Not Found means Failure
  • Resource was not found
• 405 Method Not Allowed means Failure
  • An invalid HTTP method was attempted
• 410 Gone means Failure
  • A method was attempted that is no longer supported. E.g. mobile apps can test for this condition and if it occurs, tell the user to upgrade
• 500 Internal Server Error means Failure
  • The server encountered an unexpected condition

####Sample API URLs

• api/v1/resume
  • for GET and POST
• api/v1/resume/:slug/
  • for GET, PUT, DELETE
• api/v1/job
  • for GET and POST
• api/v1/job/:slug/
  • for GET, PUT, DELETE
• Same goes for say api/v1/education and api/v1/experience
• slug represents a variable (e.g. the resume id)

####Example API Commands

A common HTTP library is cURL. Assumming a local dev server running at http://127.0.0.1:8000, here are some sample commands.

• GET with curl -v http://127.0.0.1:8000/api/v1/experiences/
• DELETE with curl -v -X DELETE http://127.0.0.1:8000/api/v1/experiences/2/
• POST with authentication using curl: curl -v -X POST http://127.0.0.1:8000/api/v1/experiences/ --data "title=mytitle"
• POST with authentication using http: http -a will@jobwaffle.com:test POST http://127.0.0.1:8000/api/v1/experiences/ title='jobtitle' q_like_dislike='stuff'

####Rate limiting

It is standard practice to rate limit access to an API. At a minimum, include these headers.

• 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. Note: do not use a UNIX timestamp (seconds since epoch) for this field.

####Considerations when making a RESTful API

• Version the API
  • If the API is still being used by someone, it doesn’t force them to update their code.
  • Even if you think there’s only going to be one version, someone will probably ask for version 2 so just put /api/v1/ instead of just /api/
• Each state should have all the information necessary
  • Don’t create just a direct link between resources and the model because this fails when you want to return a denormalized model.
  • For example don’t create links like this, {'resume': 'will', education: [1, 2, 3]} should be {'resume': 'will', education: [ 'api/v1/education/1', 'api/v1/education/2', 'api/v1/education/3' ]}
  • If we use the first example we don’t know how to construct the url for education (we only have 1, 2, 3).
  • If we use the latter example we have the complete web URL
• Don’t hardcode the format
  • For example, ?format=JSON, ?format=XML allows you to specify the format; the output format should be determined from the HTTP ‘Accept’ header
• Consistent Naming (Plural or singular)
  • I think either is fine (as long as it’s consistent) or go with whatever your company has already. Some say use plural because lots of file structures are setup that way (e.g. Program Files in Windows). Some say use singular because that’s how database table names work.
• Documentation - Always have good public documentation.
  • My favorite so far is the stripe api. Codecademy also has a list of API lessons where you can learn how to use the ‘requests’ library to interface with them.
• Security - Make all API requests over HTTPS (which is HTTP over SSL) for security purposes
  • People might be accessing the API through a coffee shop or airport wifi that isn’t secure and the communication isn’t encrypted. Someone can eavesdrop or impersonate someone if the credentials are openly accessible

##Authentication

Authentication is determining who the user is (Note: This is different than Permissions, which checks if the credentials has the permission to allow or disallow an action). If you’re implementing a server side authentication using an API, you can do a Cookie-Based Authentication (that uses server side cookies to authenticate the user on every request) or a Token-Based Authentication (that rlies on a signed token that is sent to the server on each request).

Token Benefits

Tokens are stateless (i.e. helps with server side scalability) so don’t require a session store, the token is a self-contained entity that has all the user information.

With Tokens, you can have your server as just an API while the rest of your assests (the HTML, images, javascript, etc) can be served from a CDN.

##Django REST Framework

Authentication is how we check who the user is (normally by username, password, or some type of session or token). E.g. BasicAuthentication, SessionAuthentication, TokenAuthentication. If no authentication is specified, we get a request.user is set to an instance of django.contrib.auth.models.AnonymousUser and request.auth is set to None.

Permission is what we check to see if the logged in user should be allowed or disallowed to do an action. E.g. IsOwnerOrReadOnly, IsAuthenticatedOrReadOnly

ViewSet is a single class that lets you combine the logic of a set of related views. In other REST Frameworks, this might be called ‘Resources’ or ‘Controllers’.

• In DRF, a ViewSet is a class-based view that does not provide implementation of actions like .get() or .post() and instead provides actions like .list(), .create(), .retrieve(), .update(), .partial_update(), and .destroy().
• In DRF, a GenericViewSet inherits from GenericAPIView and provides default set of get_object, get_queryset methods, but also does not provide actions by default.
• In DRF, a ModelViewSet inherits from GenericAPIView and provides actions like .list(), .retrieve(), .create(), .update(), and .destroy(). You only need to provide the queryset and serializer_class attributes.

ModelViewSet takes your existing base class and provides some default behavior, like a set of views specifically for listing, creating, retrieving, and destroying objects of a Model.

Related Posts

• 11 May 2023 DBT
• 30 Oct 2022 Godot
• 16 Oct 2022 AWS Fargate