HTTP Status codes
[Link]
HTTP STATUS CODE
ERROR 418
Im a teapot
DESCRIPTION
SUCCESS
200 OK
Basic success code. Works for the general cases.
Especially used on successful first GET requests or PUT/PATCH updated content.
201 Created
Indicates that a resource was created. Typically responding to PUT and POST requests.
202 Accepted
Indicates that the request has been accepted for processing.
Typically responding to an asynchronous processing call (for a better UX and good performances).
RESTful API
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.
Creating and providing a state of the art API requires taking into
account:
R
ESTful API principles as described in the literature (Roy Fielding,
Leonard Richardson, Martin Fowler, HTTP specification)
204 No Content
The request succeeded but there is nothing to show. Usually sent after a successful DELETE.
T
he API practices of the Web Giants
Nowadays, two opposing approaches are seen.
206 Partial Content
The returned resource is incomplete. Typically used with paginated resources.
CLIENT ERROR
General error for a request that cannot be processed.
400 Bad Request
GET /bookings?paid=true
400 Bad Request
{"error":"invalid_request", "error_description":"There is no paid property"}
Purists insist upon following REST principles without compromise.
Pragmatics prefer a more practical approach, to provide their
clients with a more usable API. The proper solution often lies in
between.
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.
To facilitate and accelerate the design and development of your
APIs, we share our vision and beliefs with you in this Reference Card.
They come from our direct experience on API projects.
I do not know you, tell me who you are and I will check your permissions.
401 Unauthorized
GET /bookings/42
401 Unauthorized
{"error:"no_credentials", "error_description":"You must be authenticated"}
Your rights are not sufficient to access this resource.
403 Forbidden
We believe that API
IS THE ENGINE OF
WE KNOW that the Web infiltrates
AND
transforms COMPANIES
WE WORK +OGETHER,
with passion, TO CONNECT
BUSINESS & IT
We help you CREATE
The resource you are requesting does not exist.
404 Not Found
OCTO Technology 2015 - All rights reserved
DIGI+AL STRATEGY
GET /hotels/999999
404 Not Found
{"error":"not_found", "error_description": "The hotel 999999 does not exist"}
Either the method is not supported or relevant on this resource or the user does not have the permission.
405 Method Not Allowed
PUT /hotels/999999
405 Method Not Allowed
{"error":"not_implemented", "error_description":"Hotel creation not implemented"}
There is nothing to send that matches the Accept-* headers. For example, you requested a resource
in XML but it is only available in JSON.
406 Not Acceptable
GET /hotels
Accept-Language: cn
406 Not Acceptable
{"error": "not_acceptable", "error_description":"Available languages: en, fr"}
SERVER ERROR
500 Internal Server Error
[Link]
Anytime, Anywhere, Any device are the key problems
of digitalisation. API is the answer to Business
Agility as it allows to build rapidly new GUI for
upcoming devices.
An API layer enables
C
ross device
3
60 customer view
Open API allows
T
o outsource innovation
T
o create new business
models
Embrace WOA
Web Oriented Architecture
B
uild a fast, scalable & secured
REST API
B
ased on: REST, HATEOAS,
Stateless decoupled
-services, Asynchronous
patterns, OAuth2 and OpenID
Connect protocols
L everage the power of your
existing web infrastructure
DISCLAMER
The request seems right, but a problem occurred on the server. The client cannot do anything about that.
[Link]@[Link]
Why an API
strategy?
C
ross channel
OPPORTUNITIES AND EMBRACE
THE WEB Inside & Out
GET /bookings/42
403 Forbidden
{"error":"protected_resource", "error_description":"You need sufficient rights"}
GET /users
500 Internal server error
{"error":"server_error", "error_description":"Oops! Something went wrong"}
This Reference Card doesnt claim to be absolutely accurate. The
design concepts exposed result from our previous work in the REST
area. Please check out our blog [Link] and feel free
to comment or challenge this API cookbook. We are really looking
forward to sharing with you.
General concepts
URLs
GRANULARITY
KISS
Anyone should be able to use your API without
having to refer to the documentation.
se standard, concrete and shared terms,
U
not your specific business terms or acronyms.
Medium grained resources
You should use medium grained, not fine nor
coarse. Resources shouldnt be nested more
than two levels deep:
ever allow application developers to do
N
things more than one way.
esign your API for your clients (Application
D
developers), not for your data.
SECURITY
OAuth2/OIDC & HTTPS
You should use OAuth2 to manage Authorization.
OAuth2 matches 99% of requirements and client
typologies, dont reinvent the wheel, youll fail.
You should use HTTPS for every API/OAuth2
request. You may use OpenID Connect to
handle Authentication.
GET /users/007
{ "id:"007",
"first_name:"James",
Target main use cases first, deal with
exceptions later.
"name":"Bond",
"address":{
GET /orders, GET /users, GET /products, ...
www.
"street":Horsen Ferry Road",
city":{"name":"London"}
API DOMAIN
NAMES
You may consider the following five
subdomains:
Production: [Link]
Test: [Link]
CURL
Developer portal:
[Link]
Production: [Link]
You should use CURL to share examples,
which you can copy/paste easily.
nouns
verbs
user(s)
NOUNS
You should use nouns, not verbs (vs SOAP-RPC).
GET /orders not /getAllOrders
HIERARCHICAL
STRUCTURE
You should use plural nouns, not singular
nouns, to manage two different types of
resources:
Collection resource: /users
Instance resource: /users/007
You should remain consistent.
GET /users/007 not GET /user/007
You should leverage the hierarchical nature
of the URL to imply structure (aggregation or
composition). Ex: an order contains products.
VERSIONING
GET /orders/1234/products/1
CONSISTENT
CASE
CRUD-LIKE OPERATIONS
PLURALS
You should make versioning mandatory in the
URL at the highest scope (major versions).
You may support at most two versions at the
same time (Native apps need a longer cycle).
GET /v1/orders
You may choose between snake_case or
camelCase for attributes and parameters,
but you should remain consistent.
Test: [Link]
/V1/
/V2/
GET /orders?id_user=007
or GET /orders?idUser=007
-H "Accept: application/json" \
-H "Authorization: Bearer at-80003004-19a8-46a2-908e-33d4057128e7" \
[Link]
/V3/
/V4/
POST /specific-orders
Query strings
GET /restaurants/search?type=thai
You may use the Google way to perform a
global search on multiple resources.
URL RESERVED
WORDS :
PARTIAL
RESPONSES
You should use partial responses so
developers can select which information they
need, to optimize bandwidth (crucial for
mobile development).
GET /search?q=running+paid
FIRST, LAST, COUNT
Use /first to get the 1st element
GET /orders/first
{ "id":"007",
"firstname":"James",
"name":"Bond",
You ought to use ? to filter resources
or (multiple URIs may refer to the same resource)
Use /last to retrieve the latest resource of a
collection
address:{"street":"Horsen Ferry Road"}
GET /orders/last
GET /users/007/orders?state=paied
200 OK
{"id":"5678", "state":"running"}
PAGINATION
You may use a range query parameter. Pagination is mandatory: a default pagination has to be
defined, for example: range=0-25.
The response should contain the following headers: Link, Content-Range, Accept-Range.
Note that pagination may cause some unexpected behavior if many resources are added.
SORT
Use ?sort =atribute1,atributeN to sort resources.
By default resources are sorted in ascending order.
Use ?desc=atribute1,atributeN to sort resources
in descending order
GET/restaurants?sort=rating,reviews,name;desc=rate,reviews
/orders?range=48-55
206 Partial Content
Content-Range: 48-55/971
Accept-Range: order 10
Link : <[Link] rel="first",
<[Link] rel="prev",
<[Link] rel="next",
<[Link] rel="last"
Use ISO 8601 standard for Date/Time/Timestamp:
1978-05-10T[Link]+00:00 or 1978-05-10
Add support for different Languages.
Accept-Language: fr-CA, fr-FR not ?language=fr
Content negotiation is managed only in a pure
RESTful way. The client asks for the required
content, in the Accept header, in order of
preference. Default format is JSON.
Accept: application/json, text/plain not /[Link]
{"id":"1234", "state":"paid"}
200 OK
GET /orders?state=payed&id_user=007
CONTENT
NEGOTIATION
I18N
200 OK
GET /users/007?fields=firstname,name,address(street)
FILTERS
INSTANCE : /ORDER/{ID}
GET
Read a list of orders. 200 OK.
Read the details of a single order. 200 OK.
POST
Create a new order. 201 Created.
PUT
Full Update: 200 OK./ Create a specific order:
201 Created.
PATCH
Partial Update. 200 OK.
DELETE
Delete order. 204 OK.
POST is used to Create an instance of a collection.
The ID isnt provided, and the new resource
location is returned in the Location Header.
POST /orders {"state":"running", id_user":"007"}
201 Created
Location: [Link]
But remember that, if the ID is specified by
the client, PUT is used to Create the resource.
PATCH /orders/1234 {"state":"paid"}
200 Ok
PUT is used for Updates to perform a full
replacement.
PUT /orders/1234 {"state":"paid", "id_user":"007"}
200 Ok
GET is used to Read a collection.
GET /orders
200 Ok
[{"id":"1234", "state":"paid"}
{"id":"5678", "state":"running"}]
GET is used to Read an instance.
GET /orders/1234
200 Ok
{"id":"1234", "state":"paid"}
Other key concepts
SEARCH
You should use /search keyword to perform
a search on a specific resource.
COLLECTION: /ORDERS
PATCH is commonly used for partial Update.
If you have to use more than one word in URL,
you should use spinal-case (some servers
ignore case).
-d {"state":"running"} \
HTTP VERB
PUT /orders/1234
201 Created
POST/orders {"id_user":"007"}
or POST/orders {"idUser":"007"}
CURL X POST \
Use HTTP verbs for CRUD operations (Create/Read/Update/Delete).
Use /count to get the current size of a collection
GET /orders/count
CROSS-ORIGIN
REQUESTS
NON RESOURCE
SCENARIOS
In a few use cases we have to consider operations
or services rather than resources.
You may use a POST request with a verb at the
end of the URI.
POST /emails/42/send
POST /calculator/sum [1,2,3,5,8,13,21]
POST /convert?from=EUR&to=USD&amount=42
RE STF UL WAY
However, you should consider using RESTful
resources first before going this way.
Use CORS standard to support REST API
requests from browsers (js SPA).
But if you plan to support Internet Explorer
7/8 or 9, you shall consider specifics endpoints
to add JSONP support.
HATEOAS
All requests will be sent with a GET method!
C
ontent negotiation cannot be handled with
Accept header in JSONP.
Payload cannot be used to send data.
Your API should provide Hypermedia links in order to be completely discoverable. But keep in
mind that a majority of users wont probably use those hyperlinks (for now), and will read the API
documentation and copy/paste call examples.
So, each call to the API should return in the Link header every possible state of the application
from the current state, plus self.
200 OK
{"2"}
You may use RFC5988 Link notation to implement HATEOAS :
POST /orders
and
/[Link]?method=POST&callback=foo
GET /orders/1234
and
/orders/[Link]?callback=foo
GET /orders
PUT /orders/1234
and
and
/[Link]?callback=foo
/orders/[Link]?method=PUT&callback=foo
Warning: a web crawler could easily damage your application with a method parameter. Make
sure that an OAuth2 access_token is required, and an OAuth2 client_id as well.
GET /users/007
< 200 Ok
< { "id":"007", "firstname":"Mario",...}
< Link : <[Link] rel="self"; method:"GET",
<[Link] rel="addresses"; method:"GET",
<[Link] rel="orders"; method:"GET"
