An application programming interface (API) is a set of routines, protocols, and tools for building software applications. An architectural style called REST (Representational State Transfer) states that web applications must use HTTP requests to GET, PUT, POST and DELETE data.

Organizations create a public API to build their web app but once an RESTful API design is built and released, it’s quite difficult to make significant changes. Thus, it’s imperative to get it as much right as possible at the very start. This is where you need strict RESTful API guidelines. Our hope is that this post can help you stick to them.

restful api guidelines

Resources (URIs)

1) Names and Verbs

Use concrete names and not action verbs to describe resources:

The RESTful approach to use is:

GET /users/1234POST /users (with JSON describing a user in the body)DELETE /addresses/1234

Well, for years, programmers used action verbs in order to establish services in an RPC way, for example: getUser(1234)createUser(user)deleteAddress(1234)

2) URI Case

There are three main types of case conventions in a program for naming resources like CamelCase, snake_case and spinal-case. These are just a way of naming the resources while avoiding apostrophes, spaces and other punctuation marks or characters.

3) CamelCase

CamelCase has been widely used by the Java language. It emphasis the beginning of each work by marking the first letter in uppercase. For instance: currentUser, camelCase, etc.

4) snake_case

The snake-case has been generally used for years by C programmers, and more recently in Ruby. The words are separated by underscores “”, thus letting an interpreter or a compiler understand it as a single symbol, but also allowing readers to separate words fluently.

5) spinal-case

The spinal-case is similar to the snake case but uses hyphen to separate words. The uses are also quite similar to those of snake case. Well, it is also the traditional way of naming files and folders in Linux and UNIX systems.

api design

HTTP Methods

One of the major objectives of the RESTful API guidelines for design is to use HTTP as an application protocol to avoid shaping an RESTful API design. Using HTTP verbs systematically will allow a program to perform the work handling recurrent CRUD operations.

Most common methods are usually observed:

1) GET – To retrieve information from a given server using a given URI.

2) HEAD – Similar to GET, but transfers only the header section and status line.

3) POST – This method is used to send information to the server using HTML forms.

4) PUT – Replaces all current representations of the target resource with the uploaded content.

5) DELETE – Removes all current representations of the target resource given by a URI.

6) OPTIONS – Describes the communication options for the target resource.

HTTP Headers

The HTTP header provides required data about the response or request. There are four types of HTTP header messages.

1) General Header – Applicability for both response and request messages.

2) Client Request Header – Only applicable for request messages.

3) Server Response Header – Only applicable for response messages.

4) Entity Header – This defines meta information about the body.

Status Codes

The status code is very important, you make use of the proper HTTP Status Codes, especially when mocking RESTful API guidelines or UX design. The most commonly used status codes:

  • 200 – OK: Everything is working.
  • 201 – CREATED: New resource has been created.
  • 204 – NO CONTENT:No response body or the resource has been successfully deleted.
  • 304 – NOT MODIFIED:Data has not changed
  • 400 – BAD REQUEST:Cannot be served or the request was invalid
  • 401 – UNAUTHORIZED: The request needs user authentication.
  • 403 – FORBIDDEN: The request has been refused or the access is not allowed, but the server accepted the request.
  • 404 – NOT FOUND: Wrong URL or no resource behind the URI.

restful design

Author Bio

Natasha is a Content Manager at SpringPeople. She has been in the edu-tech industry for 7+ years. She has been writing on web technologies, technology trends, corporate training which finds its way to various technology websites on World Wide Web. With a aim to provide the best bona fide information on tech trends, she is associated with SpringPeople. SpringPeople is a global premier training provider for high-end and emerging technologies, methodologies and products. Partnered with parent organizations behind these technologies, SpringPeople delivers