Designing a RESTful API

  • Verb: Which is the action itself, for example, Get, Post, Put, and so on
  • Headers: Which contains the information about the request; It’s possible to add some useful information like a cookie, a JWT token, and others.
  • Content: Where the information that needs to be written is added. For example, when a new customer is being inserted, the customer data will be in the request message.
  • Status code — Each status code means something, for example: 200 means “ok”, 201 means “created”, 404 means “Bad Request”, and so on
  • Headers — Can contain some useful information
  • Content — Any content that the server sends back. For example, when a list of customers is requested, this list will come in the response message.
  • GET — which request a representation of a specific resource. It is used only to return data.
  • POST — which is used to submit an entity to a specific resource. It is used to create a new resource.
  • PUT — which is used to replace all the properties of a resource. It us used to update a resource.
  • PATCH — which is used to apply partial modifications (this is used when it’s not necessary to update all the resource, but only part of it).
  • DELETE — which is used to delete a resource.
  • 200 — Ok: This status means that the request was successful.
  • 201 — Created: This status means that the request has succeeded and a new resource has been created as a result. This is usually returned after a POST request.
  • 204 — No Content: We can return this status when we do not want to return anything.
  • 400 — BadRequest: This is a generic status for error. It means that the server could not understand the request due to invalid syntax.
  • 401 — Unauthorized: This status means that the client is not authenticated, and he should authenticate to do the request.
  • 403 — Forbidden: This status means that the client is authenticated but he does not have permission to do what he is trying to do. Unlike 401, the client’s identity is known to the server.
  • 404 — Not found: This status means that the server could not find the requested resource.
  • 500 — Internal Server Error: This is a generic answer from REST API, it means that the server has encountered a situation it doesn’t know how to handle.
  • 503 — Service Unavailable: This status means that the server is not ready to handle the request.
  • Client-server — Separation of concerns is the principle behind the client-server constraints. By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components. Perhaps most significant to the Web, however, is that the separation allows the components to evolve independently, thus supporting the Internet-scale requirement of multiple organizational domains.
  • Stateless — The communication must be stateless in nature. Each request from the client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
  • Cacheable — Cache constraints require that the data within a response to a request be implicitly or explicitly labelled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests. All the requests you made should support cacheability.
  • Uniform interface — By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability.
  • Layered system — The layered system style allows an architecture to be composed of hierarchical layers by constraining component behaviour such that each component cannot “see” beyond the immediate layer with which they are interacting.
  • Code on demand (optional) — REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented. Allowing features to be downloaded after deployment improves system extensibility. However, it also reduces visibility, and thus is only an optional constraint within REST.
GET /api/books         (to get all the books)
GET /api/books/1 (to get a single book searching by id 1)
PUT /api/books/1 (to update a book with id 1)
DELETE /api/books/1 (to delete a book with id 1)
POST /api/books (to create a book)
If-Match: "bfc13a64729c4290ef5b2c2730249c88ca92d82d"

If-Match: "67ab43", "54ed21", "7892dd"
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
ETag: W/"33a64df551425fcc55e4d42a148795d9f25f89d4"
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
  • a change in the format of the response data for one or more calls
  • a change in the request or response type (i.e. changing an integer to a float)
  • removing any part of the API
  • Versioning using the API Version in the URI
  • Versioning using a Query String
  • Versioning with Custom Request Header
  • Versioning with Accept Header
  • Versioning with Content Type
// or using the scenario from the previous example:GET /api/v2/books
GET /api/v2/books/1
PUT /api/v2/books/1
DELETE /api/v2/books/1
POST /api/v2/books or using the scenario from the previous example:GET /api/books?v=2
GET /api/books/1?v=2
PUT /api/books/1?v=2
DELETE /api/books/1?v=2
POST /api/books?v=2
GET /api/books HTTP/1.1
Host: localhost:5001
Content-Type: application/json
X-Version: 2
// or:Accept-version: v1
Accept-version: v2
GET /api/books HTTP/1.1
Host: localhost:5001
Content-Type: application/json
Accept: application/json;version=2
GET /api/books HTTP/1.1
Host: localhost:5001
Content-Type: application/vnd.applicationname.v1+json
Accept: application/vnd.applicationname.v1+json
  • The API will make use of private or personalized data
  • The API will send sensitive data access the network
  • The API will use any kind of credentials
  • The API will try to protect against the overuse of your servers
  • Cookies — Use cookies is easy and common, but is not so secure. Depending on the level of security that you need, cookies can be a good option, but if you need something more secure, use another approach. An HTTP cookie (web cookie, browser cookie) is a small piece of data that a server sends to the user’s web browser. The browser may store it and send it back with later requests to the same server. Typically, it’s used to tell if two requests came from the same browser — keeping a user logged-in, for example. It remembers stateful information for the stateless HTTP protocol.
  • Basic Auth — This is also used a lot, and it is easy to implement. Basic Auth allows you to pass the information in the query string or in the headers, with the credentials to be validated on the server. This is also not so secure because can leak the username and password from the users. The credentials will be sent on every request and someone can intercept and get them.
  • Token Based Auth — This is the most commonly used and has a mix of being secure and simple. There is a standard for these tokens and there is usually middleware that will support creating and validating these tokens on most platforms.
  • OAuth — OAuth has a couple of standards and it is used to allow trusted third parties to identify users. This way the application that is using OAuth never gets the credential. So for example, if you want to login you can use your Gmail or Microsoft account, instead of informing username and password.
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
  • Information about the user
  • Claims for the kind of rights it has
  • Validate Signature
  • Other information



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Henrique Siebert Domareski

Henrique Siebert Domareski

I've been working with software development with .NET since 2011, and love programming and solve problems using clean code particles.