23/10/2018 5 Basic REST API Design Guidelines

 MENU

5 Basic REST API Design

Guidelines
02 OCTOBER 2016 on REST API, RestCase, Guidelines, Design

As soon as we start working on an API, design issues arise. A

robust and strong design is a key factor for API success. A poorly
designed API will indeed lead to misuse or – even worse – no use
at all by its intended clients: application developers.

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 1/12
23/10/2018 5 Basic REST API Design Guidelines

Creating and providing a state of the art API requires taking into
account:

RESTful API principles as described in the literature (Roy

Fielding, Martin Fowler, HTTP speci cation…)

The API practices of the Web Giants like Google, Microsoft,

Facebook, PayPal and other big companies.

Designing a REST API raises questions and issues for which there
is no universal answer. REST best practices are still being
debated and consolidated, which is what makes this job
fascinating.

Here are the 5 basic design guidelines that make a RESTful API:

1. Resources (URIs)

2. HTTP methods

3. HTTP headers

4. Query parameters

5. Status Codes

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 2/12
23/10/2018 5 Basic REST API Design Guidelines

Let's go over each one and explain a bit.

1. Resources (URIs)
Names and Verbs
To describe your resources, use concrete names and not action
verbs.
For decades, computer scientists used action verbs in order to
expose services in an RPC way, for instance:
getUser(1234) createUser(user) deleteAddress(1234)

By contrast, the RESTful approach is to use:

GET /users/1234 POST /users (with JSON describing a user in

the body) DELETE /addresses/1234

URI case
When it comes to naming resources in a program, there are 3
main types of case conventions: CamelCase, snake_case, and
spinal-case. They are just a way of naming the resources to
resemble natural language while avoiding spaces, apostrophes,
and other exotic characters. This habit is universal in
programming languages where only a nite set of characters is
authorized for names.

CamelCase

CamelCase has been popularized by the Java language. It intends

to emphasize the beginning of each word by making the rst
letter uppercase. E.g. camelCase, currentUser, etc. Aside from
debates about its readability, its main drawback is to be
ine ective in contexts which are not case sensitive.

snake_case

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 3/12
23/10/2018 5 Basic REST API Design Guidelines

snake_case has been widely used for years by C programmers,

and more recently in Ruby. Words are separated by underscores
“_”, thus letting a compiler or an interpreter understand it as a
single symbol, but also allowing readers to separate words
uently. However, its popularity has decreased due to a lot of
abuses in C programs with over-extended or too short names.
Unlike camel case, there are very few contexts where snake case
is not usable. Examples: snake_case, current_user, etc.

spinal-case

spinal-case is a variant of snake case which uses hyphens “-” to

separate words. The pros and cons are quite similar to those of
snake case, with the exception that some languages do not allow
hyphens in symbol names (for variable, class, or function
naming). You may nd it referred to as lisp-case because it is the
usual way to name variables and functions in Lisp dialects. It is
also the traditional way of naming folders and les in UNIX and
Linux systems. Examples: spinal-case, current-user, etc.

According to RFC3986, URLs are “case sensitive” (except for the

scheme and the host).
In practice, though, a sensitive case may create dysfunctions
with APIs hosted on a Windows system.

RestCase
Get an invitation to RestCase private beta

email address

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 4/12
23/10/2018 5 Basic REST API Design Guidelines

Subscribe

It is recommended to use spinal-case (which is highlighted by

RFC3986), this case is used by Google, PayPal and other big
companies.

2. HTTP methods
As stated earlier, one of the key objectives of the REST approach
is using HTTP as an application protocol in order to avoid
shaping a homemade API.
Hence, we should systematically use HTTP verbs to describe
what actions are performed on the resources and facilitate the
developer’s work handling recurrent CRUD operations.

The following methods are usually observed:

GET
The GET method is used to retrieve information from the given
server using a given URI. Requests using GET should only
retrieve data and should have no other e ect on the data.

HEAD
Same as GET, but transfers the status line and header section
only.

POST
A POST request is used to send data to the server, for example,
customer information, le upload, etc. using HTML forms.

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

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 5/12
23/10/2018 5 Basic REST API Design Guidelines

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

OPTIONS
Describes the communication options for the target resource.

3. HTTP headers
HTTP header elds provide required information about the
request or response, or about the object sent in the message
body.

There are 4 types of HTTP message headers:

General Header
These header elds have general applicability for both request
and response messages.

Client Request Header

These header elds have applicability only for request messages.

Server Response Header

These header elds have applicability only for response
messages.

Entity Header
These header elds de ne meta information about the entity-
body or, if no BODY is present, about the resource identi ed by
the request.

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 6/12
23/10/2018 5 Basic REST API Design Guidelines

4. Query parameters
Paging
It is necessary to anticipate the paging of your resources in the
early design phase of your API. It is indeed di cult to foresee
precisely the progression of the amount of data that will be
returned. Therefore, we recommend paginating your resources
with default values when they are not provided by the calling
client, for example with a range of values [0-25].

Filtering
Filtering consists in restricting the number of queried resources
by specifying some attributes and their expected values. It is
possible to lter a collection on several attributes at the same
time and to allow several values for one ltered attribute.

Sorting
Sorting the result of a query on a collection of resources. A sort
parameter should contain the names of the attributes on which
the sorting is performed, separated by a comma.

Searching
A search is a sub-resource of a collection. As such, its results will
have a di erent format than the resources and the collection
itself. This allows us to add suggestions, corrections, and
information related to the search.
https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 7/12
23/10/2018 5 Basic REST API Design Guidelines

Parameters are provided the same way as for a lter, through

the query-string, but they are not necessarily exact values, and
their syntax permits approximate matching.

5. Status Codes
It is very important that as a RESTful API, you make use of the
proper HTTP Status Codes especially when mocking RESTful API.

The mostly used status codes:

200 – OK
Everything is working

201 – CREATED
New resource has been created

204 – NO CONTENT
The resource was successfully deleted, no response body

304 – NOT MODIFIED

The date returned is cached data (data has not changed)

400 – BAD REQUEST

The request was invalid or cannot be served. The exact error
should be explained in the error payload. E.g. „The JSON is not
valid “.

401 – UNATHORIZED
The request requires user authentication.

403 – FORBIDDEN
The server understood the request but is refusing it or the access
is not allowed.
https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 8/12
23/10/2018 5 Basic REST API Design Guidelines

404 – NOT FOUND

There is no resource behind the URI.

500 – INTERNAL SERVER ERROR

API developers should avoid this error. If an error occurs in the
global catch blog, the stack trace should be logged and not
returned as a response.

RestCase
Get an invitation to RestCase private beta

email address

Subscribe

Summary
REST is not something new, REST is a return to the Web the way
it was before the age of the big application server, through its
emphasis on the early Internet standards, URI and HTTP.

Resource modeling requires a careful consideration based on the

business needs, technical considerations (clean design,
maintainability, etc.) and cost-bene t analysis of various
approaches discussed earlier so that the API design brings out
the best API consumer interaction experience.

We went over the basics of designing and developing RESTful

API, these guidelines hopefully will help in creating clean, easy
to use and understandable APIs.
https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 9/12
23/10/2018 5 Basic REST API Design Guidelines

Guy Levin Share this post

Read more posts by this author.   
http://www.restcase.com

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 10/12
23/10/2018 5 Basic REST API Design Guidelines

4 Comments RestCase Blog 

1 Login

 Recommend 5 t Tweet f Share Sort by Best

Join the discussion…

LOG IN WITH OR SIGN UP WITH DISQUS ?

Name

Mipam Bruining • a year ago

I think your underscores are not showing up correctly in the camecase
section...
2△ ▽ • Reply • Share ›

KinGuy Mod > Mipam Bruining • 5 months ago

Thanks for catching that, I have fixed the issue :)

△ ▽ • Reply • Share ›

Dr Esbach > Mipam Bruining • 5 months ago

One of the "very few contexts where snake case is not usable",
markdown interprets pairs of underscores as indicating italics.
△ ▽ • Reply • Share ›

KinGuy Mod > Dr Esbach • 5 months ago

Thanks :)
△ ▽ • Reply • Share ›

ALSO ON RESTCASE BLOG

Webhooks role in the API World The World of REST APIs

1 comment • 2 years ago 1 comment • a year ago
Fred Schulman — Thanks posting, i Akshay Pai — I build REST APIs to
Avatarknow more about webhooks in API. Avatarexpose the functionality I build to
other people either over the internet …

RESTFul API Versioning Insights REST API Error Handling Best

6 comments • 2 years ago Practices
Douglass Parker — All versioning 34 comments • 3 years ago
Avatarschemes suck. Don't change your Andre Figueiredo — Developer
resource types in a way that breaks … Avatarshouldn't expose any more
information data than just the error …

Subscribe to REST API and Beyond

Get the latest posts delivered right to your inbox.
https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 11/12
23/10/2018 5 Basic REST API Design Guidelines

Your email address SUBSCRIBE

or subscribe via RSS with Feedly!

READ THIS NEXT YOU MIGHT ENJOY

A Need For REST RESTful API Basic

APIs and API Guidelines
Development Your data model has started to

Management stabilize and you're in a

position to create a public API
The History Of Web Services
for your…
There is a long and rich history
of using web services to
communicate between…

REST API and Beyond © 2018 Proudly published with Ghost

https://blog.restcase.com/5-basic-rest-api-design-guidelines/ 12/12