API Governance
N. LAZRAQ
1
Agenda
2
Agenda
• What is REST ?
• Goals
• What is a good REST API ?
• Richardson Maturity Model
• Generic Rules
• Versioning
• Request Format
• Response & Error Formats
• Http Body
• List of Values
• Collection Management (pagination)
• Sorting
• Search
• Filtering
• Http Methods
• Monitoring
• Documentation
• Hypermedia (HATEOAS)
• Security (Authentication, Authorization, Integrity & CORS)
• Caching
• Rules Summary It’s one of our primary objectives this semester.
27/10/2024 © 2020 - Confidential 3
Introduction
APIs and Goals
4
What is REST ?
• REST is not a Protocol. REST is an Architecture Style
• REST stands for Representational State Transfer (of Resources)
• REST has been proposed in 2000 by « Roy Fielding »* in his doctoral dissertation, and has
inspired both the W3C Technical Architecture Group's architecture document and many who
see it as a model for how to build Web services
• REST is based on 6 constraints :
1. Client-Server system
2. Stateless : the client request must contain all the information needed for the server to answer. The
server does not handle client sessions
3. Cachability : Clients can cache responses
4. Layered system : Client doesn’t know if he directly connected to the server or goes through different
gateways/proxies
5. Code on demand
6. Uniform interface : URI / metadata / media-types / hypermedia links… * Roy Fielding Thesis link
https://www.ics.uci.edu/~fieldin
27/10/2024 © 2020 - Confidential g/pubs/dissertation/fielding_diss
ertation.pdf 5
Goals
• As an editor, Opencell must have a mature API
• The API is a differentiator, perceived as a competitive
advantage
• Have a quick TTFAC (Time To First API Call) and Happy
Developpers
• Well documented
• Keep it Simple & Stupid (KISS principle)
27/10/2024 © 2020 - Confidential 6
What is a good REST API ?
A good API is :
• Simple and externalizable
• Following HTTP Standards
• Offering good affordance
• Intuitive
• Inspired from Big Tech
« All service interfaces, without exception,
companies must be designed from the ground up to be
externalizable. That is to say, the team must
plan and design to be able to expose the
interface to developers in the outside world.
No exceptions » Jeff Bezos, Internal Communication
2002
27/10/2024 © 2020 - Confidential 7
Richardson Maturity Model
Level 3 : Hypermedia control
(HATEOAS)*
Level 2 : Using http verbs and
http response codes as much
as possible
Level 1 : Introduction of
resources
Level 0 : Using http as
transport system without web
mechanisms
* HATEOAS : Hypermedia As The Engine Of Application Sta
27/10/2024 © 2020 - Confidential 8
Rules & Specifications
HTTP From Paths to Status Codes
9
Request R or
Generic Rules GET api/v1/Users
W?
Wrong
GET api/v1/users?Firstname=Bob Wrong
• Character cases : GET api/v1/users?First-name=Bob Wrong
– Compound words use camel-
GET api/v1/users?firstName=Bob Right
case or underscore, not
hyphen GET api/v1/users?first_name=Bob Right
– Path elements are lowercase GET api/v1/users?nom=Bob Wrong
• Language: English words or GET api/v1/users?name=Bob Right
acronyms GET api/v1/search?origin=Bob.debitMemo Wrong
• Character set : UTF-8 encoded
GET api/v1/search?Accoun=- Right
• End of Line : Unix-Like (LF) Bob&subCategory=debitMemo
“billRunDates“ : “01-01-2020 31-01- Wrong
• Atomic information : One piece 2020“
of information by element “billRunStartDate“ : “01-01-2020“ Right
“billRunEndDate“ : “31-01-2020“
27/10/2024 © 2020 - Confidential 10
Fields Type Comments
Versioning Version.major String Major AP Version (must be the same as the
one in the path /vx)
Version.minor String Minor API Version
• Major version identifier in path (/vM pattern): Version.patch String (optional) Patch API Version
- Compound words use camel-case or underscore, not hyphen
- Path elements are lowercase deprecated Boolean True if the API version (vX) is deprecated
• Minor API version in case of backwards compatibility changes +
retirementDate Date Retirement date (ISO 8601 format)
documentation update
- Changing case-sensitivity (CDR -> cdr)
- Repositionning existing field
- Adding new fields
- New ressources (URIs) HTTP/1.1 200 OK
- New representation {
- New method supported "version": {
"major": "1",
• Major API version in case of non-backward compatibiliy changes + "minor": "5",
documentation update + deprecation strategy definition "patch": "8"
- Existing resource deprecated },
- Existing http method not used anymore "deprecated": true,
- Resource behavior is changing "retirementDate": "2016-01-31"
}
- New mandatory input parameters
- Hierarchical of resource rep. not preserved
• GET /version should return information about the version
API LifeCycle steps Design Dev Live Deprecated Retired
27/10/2024 © 2020 - Confidential 11
Request R or W?
Request Format GET api/v1/service_status Wrong
GET api/v1/service/status Right
• Path segment should avoid compound names
• No file extension to path segments GET api/v1/customers.json Wrong
• Variable path segments contain resource identifier
only GET api/v1/customers/24234.json Wrong
• GET must be used for data retrieval only
• POST must be used for resource creation or any GET api/v1/customers with Accept Header Right
other unmanaged operation
• PUT must be used for full update or atomic resource POST api/v1/customers/1234 + (body) Wrong
creation
• PATCH must be used for partial updates POST api/v1/customers + (body) Right
• PATCH should use either JSON or JSON-PATCH format
POST api/v1/customers/1234/subscriptions + (body) Right
• DELETE must be used for deletion only
• HTTP 1.1/ extensions method (COPY, MOVE, LOCK) PUT api/v1/customers/1234 + (body) Right
and custom HTTP Method are prohibited
• OPTIONS returns a list of http methods supported by PUT api/v1/customers/1234/subscriptions/3 + (body) Wrong
the resource
• HEAD returns the same response as GET but with no DELETE api/v1/customers?(list of search filter) Right
body (allowing clients to check ressource existence)
DELETE api/v1/customers/24 Right
27/10/2024 © 2020 - Confidential 12
Response Format : Methods
Method Operation Single Resource Collection HTTP Specific Response body
Status Headers
GET Retrieve customer YES YES 200 No Resource Representation
1234 or all customers
POST Create new customer YES NO 201 Content- New resource representation
Location
201 Location No body
PUT Create customer 1234 YES NO 201 Content- New resource representation
Location
201 Location No body
PUT Update customer YES NO 200 Content- The updated resource representation
1234 Location
204 Location No body
PATCH Partial update of YES NO 200 Content-
customer Location
204 Location No body
DELETE Delete customer 123 YES YES 204 None No body
or all
27/10/2024 © 2020 - Confidential 13
Request Format : Query-String
• Query-string paremeter names are
lowercase, case-insensitive and
Request R or W?
bound of alpha/digits/underscore
chars only and special characters api/v1/users?firstName=Cédric Wrong
UTF-8 encoded api/v1/users?firstName=C%E9%dric Wrong
• Multi-valued query-string values api/v1/users?firstName=C%C3%A9dric Right
must use comma as separator
api/v1/customers/123/paymentMethod?default=1 Wrong
• If comma is a part of the value
then it should be encoded %2C% api/v1/customers/123/paymentMethod?default=true Right
• Boolean values are true or false POST api/v1/customers?sort=firstName,lastName Right
• Unknown parameters are
accepted and ignored
27/10/2024 © 2020 - Confidential 14
Request Format : Headers
• Localization should be requested using Accept-Language
header
• Accept header should be used to select MIME types (json is
default) :
• Cache-Control should be used for caching directive
• « If-Modified-Since », « If-None-Match » and « If-Unmodified-
Since » should be used for caching directive
• X-HTTP-Method-Override header to cover cases of old proxies
that only support GET and POST methods
27/10/2024 © 2020 - Confidential 15
Fields Type Comments
Response & Error Formats
code Integer
or
Business error code given to caller
string
• HTTP Status code must be used message string A short localized string that describes the
error
• Errors must set http error status, never description string Long error description, can contain precise
2xx information about which parameter is
missing, or what are the identifier
• Use « 201 Created » for new ressource acceptable values.
creation During the debugging hase, it can be used
tto return any useful serialized object or
• Use « 202 Accepted » for asynchronous technical details about the context of the
tasks error (technical/functional)
• Use « 204 No Content » for put responses infoURL String (optional) a Url to online documentation
(url) that provides more information about the
in general error
• Never define nor use custom status codes
• Header names in response are capitalized
and hyphenated HTTP/1.1 400 Bad Request
{
• Error response should be a liste of errors "errors": [{
"code": "BALANCE_INSFFICIENT",
as in the following format "message": "Insufficient balance to process purchase",
"description": "The user prepaid account has insufficient credit to
purchase the product",
"infoURL": "http://someurl.com",
}]
27/10/2024 } © 2020 - Confidential 16
HTTP Body
• Body fields are lowercase. Camel-case notation is preferred compared
to underscore compound words
• Bodies must be JSON by default. Additional Media Types may be
suported
• Must be encoded in UTF-8
• Boolean use true or false values
• Phone numbers, Languages, URL format and Email format follow RFC
standards
• Country Code follows ISO alpha 2
• Dates and Date Time follow ISO standards
• Time zone represented as UTC or as an offset from UTC in responses
• No more than 2 imbrication levels !!!!
27/10/2024 © 2020 - Confidential 17
Request R or W?
Interval of values “userIds“ : “123, 124, …“ Wrong
“userIds“ : [123, 124, …] Right
• Query-string interval of values
?interval=fromValue,toValue Right
use comma
• In bodies, use an array list of ?pricesInterval=10,18 Right
tags ?serviceDates=2020-01-01,2020-12-31 Right
• Query-string partial intervals ?partialInterval=fromValue, Right
use comma with one bound ?partialInterval=,toValue Right
?acivationDates=2020-03-01, Right
27/10/2024 © 2020 - Confidential 18
Collection Management
• Paginated responses include range and total size info using
« X-Total-Count » and « X-Result-Count » headers
• Pagination is done with « offset » and « limit » query-string
parameters
- offset (0 based): index of thefirst item to retrieve.
- limit (0 based): Max number of items to retrieve. It can be
greater than the actual number of available items
GET …/subscriptions?offset=10&limit=20
27/10/2024 © 2020 - Confidential 19
Sorting
• Sorting is done with « sort » query-string
parameter
• Use « - » sign to indicate a descending
order
• Use « , » as separator for multi-sorting
GET …/services?sort=-activationDates,code
27/10/2024 © 2020 - Confidential 20
Search
• Basic search is done using query-string
parameters
GET …/services?
27/10/2024 © 2020 - Confidential 21
Security
Authentication, Authorization & CORS
principles
22
CORS vs SOP
• Single Origin Policy (SOP) est une politique qui permet d’interdire à tout
browser qui ne se trouve pas sur l’origine du serveur de communiquer
avec ce dernier.
Ex: serveur opencellDomaine:5678
client (browser): autreDomaine:4558 (accès interdit)
client opencellDomaine:5678 (accès autorisé)
C’est ce qui est implémenté par défaut sur les serveurs Web (en particulier
pour Opencell)
• CROSS ORIGIN REQUEST SHARING (CORS)est une politique contraire au
SOP, qui veut autoriser certains clients (browsers) d’accéder à certaines
ressource du serveur web. Cela doit être configuré finement au niveau
du Serveur.
27/10/2024 © 2020 - Confidential 23
CORS Issue
• Single Origin Policy (SOP) est une politique qui permet d’interdire à tout
browser qui ne se trouve pas sur l’origine du serveur de communiquer
avec ce dernier.
Ex: serveur opencellDomaine:5678
client (browser): autreDomaine:4558 (accès interdit)
client opencellDomaine:5678 (accès autorisé)
C’est ce qui est implémenté par défaut sur les serveurs Web (en particulier
pour Opencell)
• CROSS ORIGIN REQUEST SHARING (CORS)est une politique contraire au
SOP, qui veut autoriser certains clients (browsers) d’accéder à certaines
ressources du serveur web. Cela doit être configuré finement au niveau
du Serveur.
27/10/2024 © 2020 - Confidential 24
OAuth2.0 & OIDC ?
• « OAuth2.0 » Protocol for handling Authorization
• « OIDC » stands for « Open ID Connect »
• A layer on Top of « OAuth 2.0 »
• Every one knows about it without really knowing how it
works
• Different OAuth2.0 flows for different use cases (M2M,
Mobile, SPA…)
27/10/2024 © 2020 - Confidential 25
Client Credentials Flow (Machine to
Machine)
27/10/2024 © 2020 - Confidential 26
Resource Owner Flow (Deprecated in
2020)
27/10/2024 © 2020 - Confidential 27
Implicit Grant Flow (Deprecated in
2020)
27/10/2024 © 2020 - Confidential 28
Authorization Code Flow
27/10/2024 © 2020 - Confidential 29
Hands on
Authentication, Authorization & CORS
principles
30
