Cloud Side: REST APIs - Best practices

AnyAsASAnything As A Service
Nicolas Foata
REST architecture
(Basis & Best practices)
Public
1
http://www.anyasas.com
customer-service@anyasas.com

Plan
 I) Introduction / Reminder
 Context & reminder about service communication (time/quality)
 History & state of the art
 New Phenomenon
 Web APIs (HTTP & REST)
 II) Best practices (REST WS)
 Reminders (about bad practices, HTTP & Richardson’s maturity model)
 Prescriptions & Practices (URI, Headers & Errors)
 III) Examples (REST WS)
 Examples: GET, POST, PUT, PATCH, DELETE
 Hypermedia controls
 Lifecycle of an API
Public
2

Introduction / Reminder
Public
3

I.1) What is a service API
A set of requirements
that govern
how an application/service
can discuss with another one
Expose some:
- shared domain features
- and relevant domain data
outside the service
Technical side
Functional side
e.g: Address of a client
e.g: Use HTTP on the port 80
Define
the communication
processes
Public
4

I.2) State of the Art (about service communication)
Sigles Names Inconveniences Advantages
RPC Remote Procedure Call • Different implemented protocols
• OS/languages difficulties
XML-RPC • Messages too heavy • HTTP for transferring
• Structured data
• Not dependent of the
OS or languages
SOAP Simple Object Access Protocol • Messages too heavy
• API modification causes development on both
client and server sides (lifecycles troubles)
• Is an XML-RPC
CORBA Common Object Request Broker
Architecture
http://www2002.org/CDROM/alternate
/395/
• Messages too heavy
• OS/Language
independent
RMI Remote Method Invocation • Language dependant (Java).
• Faster than previous
ones.
Public
http://www.programmableweb.com/api-university
ALL APIs:
• Accessibility
• Ease of integration
• Agility
• Interoperability
• Speed actions
• Lifecycle independent
5

I.3) Main problems (about service communication)
Public 6
Problematic:
Several protocols of different layers exist to communicate between applications, services.
(An API must define the boundaries of a service)
In fact, all this diversity causes:
- the development of intermediate components
which are not really business valuable objects.
- some complexity to manage all of them,
- some complexity/difficulty to change, evolve the SI
when It need necessary. (Performance pbm too)
- some complexity to manage the network and the security.
Why this is a problem:
All this diversity and complexity,
have both an important impacts :
- on the costs (time, human, money)
- and on the reactivity/adaptability
of the business
Public
6

I.4) The idea
REST
REpresentational State Transfer: Really simple architecture.
• Resource Oriented Architecture
• Using HTTP verbs
CRUD
Create
Read
Update
Delete
HTTP verbs
POST
GET
PUT
DELETE
• Good design
• - Simplest for the user, less is has to do
Public
7

I.5) Why a new Phenomenon (about service communication)
15 billion/day 2011
5 billion/day
5 billion/day
8 billion/month42 billion in jan 2012
Public
8

I.6) What is really an open Web service API
API
An open API is a self-service API where we will don’t the final usage of our service.
We let the upper layers & developers make easily new businesses.
API
Offer
API
Self-service
API offer
Contract Interface Implementation
Business offer
with its SLA
Integration process
API
Offer
Docs,
SDK,
tools
Automatic
order/delivery
integration process
Support
(pre/post sales)
= +
+ +=
= + + +
A technical
consumer needs
to contact the technical and
integration teams and the
business providers
A client contact the business
to have an access to the service
via the integration team
The client directly use the on-
line service without
any time charge for the
service provider
Product/Service Organization
Public
9

Best practices
(REST WS)
Public
10

11
Bad practices
 Ambiguous
 Unuseful notion
 Unexplicit
 Adding too more information
 Un affordance (Affordance : Perceived and actual
properties of an object that give clues to its operations)
II.1) Reminder (about bad practices)
Cache trouble, really bad practice.
Apigee
examples
Public
11

II.1) Reminder (about bad practices)
12
As you can see, the API
is ambiguous, not clear
and means nothing on actions
that will be done.
Public
12

13
II.2) Reminder (about HTTP)
URL (Uniform Resource Locator)
Request
Answer
Public
13

II.3) Reminder (and about Richardson Maturity model)
http://myservice/api/v1/clients/nicolas
POST, GET, PUT, PATCH, DELETE
Create, Read, Update, Delete
Links about the available actions on a resource
Hypermedia As The Engine Of Application State
Transport protocol. e.g: HTTP
Public
14

Public
15
23 August
2017
II.4) Prescriptions & Practices (about URL & headers)
URL side
1) URL are resource oriented
2) Do not go below the resource
3) If an argument change the logic of the answer, it must be put into the URL.
Otherwise it must be into the header (e.g: authentication, format, …)
4) Avoid extensions such as .jsp, .asp, .php (the implementation information must be hidden)
5) The resource names must be in lower case, use the plural (collections) and the underscore if the resource is a composed name (snake_case)
6) A resource is a noun not a verb (except is not in CRUD operation)
7) The API version must be in the URL
8) Use query parameters for filtering, sorting or searching and for limiting fields
9) Use path parameters for identifying the resource
10) Resources and parameters are in english
11) Parameter must be process such as case insensitive
12) URL encode ( UTF_8 encode( parameters ) ) //resource must be e name, an operation is a verb
Message side (Request and answer)
Header
1) Header encoding must be: ASCII or optionally ISO-8859-1
2) MyCompany Internal field headers must be prefixed such as
X-MyCompany-<Service id>-<field>
e.g: X-MyCompany-CustomerService-ErrorMessage
3) The default charset is UTF-8 which must specified.
e.g: Content-Type: application/json; charset=UTF-8
Body
1) Body must use by default the JSON format
2) Data could be minified and compressed (LZMA)
15
Public

II.5) Prescriptions & Practices (about codes & errors)
Error side (management)
1) We have two kind of errors.
For client side ones, use 400 HTTP codes.
For servers ones, use 500.
2) However, an error must be processed
by the client, so add several information
into an answer JSON object such as:
- type
- error code
- understandable message
- help link
- date time …
- if a user makes several errors, send them
in one shot
HTTP Response codes
Header
200 OK - for GET, PUT, PACTH or DELETE and if POST already exists
201 Created - for POST
202 Accepted - for asynchronous POST
204 No Content - for DELETE (no body)
304 Not Modified - if we use a cache
400 Bad Request - The request is malformed, such as if the body
does not parse
401 Unauthorized - When no or invalid authentication details are provided.
Also useful to trigger an auth popup if the API is used from a browser
403 Forbidden - When authentication succeeded but authenticated
user doesn't have access to the resource
404 Not Found - When a non-existent resource is requested
405 Method Not Allowed - When an HTTP method is being requested
that isn't allowed for the authenticated user
410 Gone - Indicates that the resource at this end point is no longer
available. Useful as a blanket response for old API versions
415 Unsupported Media Type - If incorrect content type was provided
as part of the request
422 Unprocessable Entity - Used for validation errors
429 Too Many Requests - When a request is rejected due to rate limit
16
Public

Lifecycles & API compatibilities
Miscellaneous
• Only increment a version when a backward compatibility is broken.
http://myservice/api/v1
http://myservice/api/v2
• Do not increment a version otherwise.
• Inform the client to be TolerantReader (See Martin Fowler blog)
• Maintain two versions maximum (previous one and current)
• According the business, adapt release lifecycles
(6 months to 4 years as Ubuntu for example)
II.6) Prescriptions & Practices (about design, lifecycle and resiliency)
• A concrete API is better than an abstract one.
• An API must be easy to use so hide complexity behind
• Allow partial responses to give exactly what the user want
• Users control the way how to they use the API
• Provide an unfiform way for filtering, sorting and ordering
• Provide a way for limiting JSON fields
• API service must be specified into the FQDN or the path
(preferred DNS part with sometimes customers)
• API version must be in the path
Public
17

Examples
(REST WS)
Public
18

III.1) Examples (GET)
HTTP Request
GET https://my_service/my_api/v1/my_objects/?fields=id,name,category,url&offset=0&limit=10
&sort=name&search=category%3Dcat
GET https://my_api.my_service/v1/my_objects/3
HTTP Answer
HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8
X-Anyasas-PetService-Codes: 200
X-Anyasas-PetService-Messages: Rules 3 used
X-Anyasas-PetService-Send-Count: 2
X-Anyasas-PetService-Total-Count: 1231
X-Anyasas-PetService-Rate-Limit: 1000000
X-Anyasas-PetService-Rate-Limit-Remaining: 64390
X-Anyasas-PetService-Rate-Limit-Reset: 36043
Header
[
{
"id" : "5278",
"name" : "Aquarelle",
"category" : "Cat",
"url" : "https://cats.com/aquarelle/"
},
{
"id" : "4390",
"name" : "Doggy",
"category" : "Dog",
"url" : "https://dogs.com/mylitlledoggy/"
}
]
Body
Header
READ
Better to put metadata into the JSON to avoid proxy
• Minification
• LZMA
Public
19

III.2) Examples (POST)
HTTP Request
POST https://my_api.my_service/v1/pets
HTTP Answer (with redirection)
HTTP/1.0 201 Created
Location /v1/pets/5278
Header
{
"id": "5278",
"name": “Aquarelle",
"description": "A really nice cat with 3 colours",
“category": “Cat",
"url": "https://cat.com/aquarelle/",
"image": "https://cat.com/aquarelle/img1.png",
“nbOfColours": 3,
“nbOfLegs": 4,
“likes": “mouses"
}
BodyHeader
HTTP Answer (without redirection but with the content)
Content-Location /v1/pets/5278
Header Body
{
"id": "5278",
…
}
CREATE
20
Public

III.3) Examples (PUT)
HTTP Request
PUT https://my_api.my_service/v1/pets/5278
HTTP/1.0 200 OK
Header
{
"id": "5278",
"name": “Aquarelle",
"description": "A really nice cat with 3 colours",
“category": “Cat",
"url": "https://cat.com/aquarelle/",
"image": "https://cat.com/aquarelle/img1.png",
“nbOfColours": 3,
“nbOfLegs": 4,
“likes": “mouses"
}
BodyHeader
Header Body
{
"id": "5278",
…
// acceleration
// disappears
}
UPDATE
(all)
(replacement)
Send 201 Created if does not exist. So the client is able to know if this is an update or a creation.
21
Public

III.4) Examples (PATCH)
HTTP/1.0 200 OK
Header
HTTP Request
PATCH https://my_api.my_service/v1/pets/5278
{
"speed": 258
}
BodyHeader
HTTP/1.0 200 OK
Header Body
{
"id": "5278",
// All the
// JSON
}
UPDATE
(a part)
22
Public

III.5) Examples (DELETE)
HTTP Request
DELETE https://my_api.my_service/v1/pets/5278
HTTP Answer
HTTP/1.0 204 No Content
X-Anyasas-PetService-Messages: Found and removed
Header
Header
DELETE
HTTP Request
DELETE https://my_api.my_service/v1/pets
HTTP Answer
HTTP/1.0 204 No Content
X-Anyasas-PetService-Messages: Collection removed
Header
Header
CollectionsResource
23
Public

 JSON Hypertext
 application/hal+json
 application/hal+xml
 SIREN
III.6) Hypermedia controls
Some HATEOAS formats
24
Public

Thank you
25
Public

Appendices
26
Public

27
IV.1) Appendices: How to build/transform a service
1) Define the service offer:
• Which service to expose ?
• What are the different alternatives proposed ?
• Who are the consumers?
• What will the user need to use my service?
• Defining the business model :
• what the expected gain?
• Are we ready for a billing model ?
• What are the legal constraints associated
with my service?
• Documentation quality
1) Service
offer
definition
2) Service
technical
definition
3) Service life
In production
4) Service
promotion
4) Service promotion
• Where the service will be exposed
(catalog, discovery service …) ?
• Communication support definition.
• User feedbacks
3) Service life
• How manage transition
• Troubleshooting
management
2) Service promotion
• Define where the service will be exposed
(Amazon, Google, countries)
• Support costs
• Network impacts and costs
• Backends impacts and costs
• Service interface for monitoring,
billing, …
• Evolution management
• SLA
• Restriction management (client, time, …)
27
Public

IV.2) Appendices: API components
API gateway
API key
authentication
Traffic
management
Authorizations
(Access control)
[Format &
aggregation]
API management
API key
management
Security
policy
[Lifecycle
management]
Billing/Invoice
Monitoring
API store
Self-service
open API
Service catalogue
Third party
API
Internal developper
Bad practices, if use
for our services
Must be manage
at the service level for
each service portfolio
actor
28
Public

Real Time
IV.3) Service analysis & lambda architecture
Collecting
phase
Storage
phase
Processing
phase
Viewing
phase
Service offering
phase
Distributed
Queuing
System
e.g: Kafka
Kind of
NoSQL
e.g: Elastic
search
Stateless
Service
WSRESTAPI
SQL or NoSQL
DBs.
E.g: MongoDB
Cassandra
Neo4J
Couchbase
Stateless
Service
WSRESTAPI
Logstash
Fluentd
Scribe
Ap. Flume
Splunk
Lumberjack
t.jmalloc
or
Yet
Another
Resource
Negotiation
Process
stream
Increme
nt
view
Real
time
view
Batch
view
Hadoop
All
data
HDFS
Map
[Combine]
Reduce
Merged
view
Kibana
Grapha
na
29
Public

Cloud Side: REST APIs - Best practices

More Related Content

What's hot

Similar to Cloud Side: REST APIs - Best practices

Recently uploaded

Cloud Side: REST APIs - Best practices