REST API

1. REST-API InsideREST-API InsideREST-API InsideREST-API InsideREST-API InsideREST-API Inside
REST-API Inside
REST-API Inside
REST-API Inside
REST-API Inside
REST-API Inside
REST-API Inside
REST-API Inside
REST-API Inside
REST-API InsideREST-API Inside
Software Architects' Guide to REST API Design
Elias Hasnat | 2016-12-27

1 / 27

2. IntroductionIntroductionIntroductionIntroductionIntroductionIntroduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
IntroductionIntroduction
1. REST (Representational State Transfer)
2. API (Application Program Interfacing)
3. Digital Strategy
4. B2B Strategy
5. Security

2 / 27

3. Strategy andStrategy andStrategy andStrategy andStrategy andStrategy and
Strategy and
Strategy and
Strategy and
Strategy and
Strategy and
Strategy and
Strategy and
Strategy and
Strategy andStrategy and
EmpowermentEmpowermentEmpowermentEmpowermentEmpowermentEmpowerment
Empowerment
Empowerment
Empowerment
Empowerment
Empowerment
Empowerment
Empowerment
Empowerment
EmpowermentEmpowerment
1. The main goal of RESTful API is Business Strategy and B2B
strategy empowerment.
2. Rest API helps to provide access of the core software
application in any type of computing devices (desktop,
laptop, portable and mobile). This is the solution to the
Business Agility.

3 / 27

4. Properties of RESTful APIProperties of RESTful APIProperties of RESTful APIProperties of RESTful APIProperties of RESTful APIProperties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful API
Properties of RESTful APIProperties of RESTful API
1. Cross device information sharing
2. Cross channel information exchange
3. Web oriented architecture
4. Supported protocols are
* HATEOAS(Hypermedia as the Engine of Application State) and
* REST (Represtational State Transfer)
5. Stateless decoupled micro-services
6. Asynchronous pattern
7. Open authentication Oauth2, OpenID
8. B2B capability, BPO bunisness process outsourcing and New Business
logic opportunities

4 / 27

5. AUTHENTICATIONAUTHENTICATIONAUTHENTICATIONAUTHENTICATIONAUTHENTICATIONAUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATIONAUTHENTICATION
1. OAuth2 to manage Authentication
2. HTTPS for every API, OAuth2 request
3. Use of OpenID connect for authentication

5 / 27

6. CORE DESIGNCORE DESIGNCORE DESIGNCORE DESIGNCORE DESIGNCORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGN
CORE DESIGNCORE DESIGN
1. Follow the KISS principle
2. Use standard, concrete and shared syntaxes for the
general and easy utilization
3. Objective of the API design for clients (application
developers), more specificly no data
4. Priority given to the main use cases initially then to the
exceptions later

6 / 27

7. DOMAIN STRUCTUREDOMAIN STRUCTUREDOMAIN STRUCTUREDOMAIN STRUCTUREDOMAIN STRUCTUREDOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTURE
DOMAIN STRUCTUREDOMAIN STRUCTURE
> Production : https://api.example.com
> Staging : https://api.sandbox.example.com
> Dev Portal : https://dev.example.com
> Authentication domains
> Production : https://outh2.example.com
> Staging : https://oauth2.sandbox.example.com

7 / 27

8. API ACCESS METHODAPI ACCESS METHODAPI ACCESS METHODAPI ACCESS METHODAPI ACCESS METHODAPI ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHOD
API ACCESS METHODAPI ACCESS METHOD
General method of sharing example use is CURL method
CURL -X POST
-H "Accept: application/json"
-H "Authorization: Bearer BCD-AAA-KKK-ETC"
-d '{"status":"start"}'
https://api.example.com/v1/application/app_1/execution

8 / 27

9. USE OF NESTS inUSE OF NESTS inUSE OF NESTS inUSE OF NESTS inUSE OF NESTS inUSE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS in
USE OF NESTS inUSE OF NESTS in
RESPONSERESPONSERESPONSERESPONSERESPONSERESPONSE
RESPONSE
RESPONSE
RESPONSE
RESPONSE
RESPONSE
RESPONSE
RESPONSE
RESPONSE
RESPONSERESPONSE
The resources should not me nested more than two steps deep
> GET /applications/app_1
RESPONSE:
{
"id": "app_1",
"name": "app_1",
"location": {
"memory":"2",
"hdd":{"offset":"zxc"}
}
}

9 / 27

10. CAREFULCAREFULCAREFULCAREFULCAREFULCAREFUL
CAREFUL
CAREFUL
CAREFUL
CAREFUL
CAREFUL
CAREFUL
CAREFUL
CAREFUL
CAREFULCAREFUL
AUTHENTICATIONAUTHENTICATIONAUTHENTICATIONAUTHENTICATIONAUTHENTICATIONAUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATION
AUTHENTICATIONAUTHENTICATION
1. Web crawler or bots are used for DDoS attacks and so on,
2. Hence for each API access is sould be ensured to use
> OAuth2 Access_Token
> OAuth2 Client_ID

10 / 27

11. CORS OPTIONCORS OPTIONCORS OPTIONCORS OPTIONCORS OPTIONCORS OPTION
CORS OPTION
CORS OPTION
CORS OPTION
CORS OPTION
CORS OPTION
CORS OPTION
CORS OPTION
CORS OPTION
CORS OPTIONCORS OPTION
1. Use CORS(Cross origin requests) for accessing from
SPA(Single Page Application), Landing Page, js etc.
2. For IE 7,8,9 JSONP is suitable but the limitation is that
JSONP can not do content negotiation using Accept
Header. Another limitation is Data could not be sent using
Payload. Overall every request should be sent using GET
method.

11 / 27

12. CONTENT NEGOTIATIONCONTENT NEGOTIATIONCONTENT NEGOTIATIONCONTENT NEGOTIATIONCONTENT NEGOTIATIONCONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATION
CONTENT NEGOTIATIONCONTENT NEGOTIATION
1. Content negotiation is done by providing the required
content header from the client.
2. The default format of Accept Header is JSON.
> Accept: application/json
> Accept: text/plain
> Accept: application/xml

12 / 27

13. HATEOASHATEOASHATEOASHATEOASHATEOASHATEOAS
HATEOAS
HATEOAS
HATEOAS
HATEOAS
HATEOAS
HATEOAS
HATEOAS
HATEOAS
HATEOASHATEOAS
1. For discoverability every API should be provided with the
Hypermedia links using every possible state of the
application.
2. RFC5988 Link notation could be used for HATEOAS
implementation.
GET /app/app_1
< 200 Ok
< { "id":"app_1", " rstname":"Application One",...}
<Link:<https://api.example.com/v1/apps>; rel="self"; method:"GET",
<https://api.example.com/v1/locations/app_1>; rel="locations";
method:"GET"

13 / 27

14. i18N Localizationi18N Localizationi18N Localizationi18N Localizationi18N Localizationi18N Localization
i18N Localization
i18N Localization
i18N Localization
i18N Localization
i18N Localization
i18N Localization
i18N Localization
i18N Localization
i18N Localizationi18N Localization
1. ISO 8601 for Date/Time/Timestamp: 1978-05-
10T06:06:06+00:00
2. RFC 7231 Languages
Accept-Language: de
Accept-Language: de-CH
Accept-Language: en-US,en;q=0.5

14 / 27

15. SEARCHSEARCHSEARCHSEARCHSEARCHSEARCH
SEARCH
SEARCH
SEARCH
SEARCH
SEARCH
SEARCH
SEARCH
SEARCH
SEARCHSEARCH
"/search" keyword should be used for search operation.
GET /applications/search?type=cron

15 / 27

16. FILTERFILTERFILTERFILTERFILTERFILTER
FILTER
FILTER
FILTER
FILTER
FILTER
FILTER
FILTER
FILTER
FILTERFILTER
"?" should be used as filter keyword.
GET /application/app_1/status?state=running
GET /applications/status?state=running&app_id=app_1

16 / 27

17. PAGINATIONPAGINATIONPAGINATIONPAGINATIONPAGINATIONPAGINATION
PAGINATION
PAGINATION
PAGINATION
PAGINATION
PAGINATION
PAGINATION
PAGINATION
PAGINATION
PAGINATIONPAGINATION
1. For pagination purposes query range should be used and
also there should be a default pagination range for example
range=0-10.
2. The response header must contain the range information
as follows Link, Content-Range, Accept-Range.
/applications?range=13-27
206 Partial Content
Content-Range: 13-27/89
Accept-Range: order 10
Link:<https://api.example.com/v1/applications?range=0-9>; rel="first",
<https://api.example.com/v1/applications?range=10-19>; rel="prev",
<https://api.example.com/v1/applications?range=20-29>; rel="next",
<https://api.example.com/v1/applications?range=80-89>; rel="last"

17 / 27

18. PARTIAL RESPONSEPARTIAL RESPONSEPARTIAL RESPONSEPARTIAL RESPONSEPARTIAL RESPONSEPARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSE
PARTIAL RESPONSEPARTIAL RESPONSE
For the better use of bandwidth the partial response is
used rather than showing all huge data.
/applications/app_1?fields= name,location
200 OK
{
"name": "app_1",
"location": {
"memory":"2",
"hdd":{"offset":"zxc"}
}
}

18 / 27

19. SORTSORTSORTSORTSORTSORT
SORT
SORT
SORT
SORT
SORT
SORT
SORT
SORT
SORTSORT
1. For sorting the query result "?sort=atribute1,atributeN" is
used.
2. By default resources are sorted in ascending order.
Use of "?desc=atribute1,atributeN" to sort resources in descending order
GET /applications?sort=rating,reviews,name;desc=rate,reviews

19 / 27

20. FIRSTFIRSTFIRSTFIRSTFIRSTFIRST
FIRST
FIRST
FIRST
FIRST
FIRST
FIRST
FIRST
FIRST
FIRSTFIRST
"first" keyword is used to get the first element.
>GET /applications/first
200 OK
{"id":"app_1", "state":"free"}

20 / 27

21. LASTLASTLASTLASTLASTLAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LAST
LASTLAST
"last" keyword is used to get the last element.
>GET /applications/last
200 OK
{"id":"app_89", "state":"in-app-purchase"}

21 / 27

22. COUNTCOUNTCOUNTCOUNTCOUNTCOUNT
COUNT
COUNT
COUNT
COUNT
COUNT
COUNT
COUNT
COUNT
COUNTCOUNT
"count" keyword is used to get the count of the resulting
elements.
GET /applications/count
200 OK
{"count":"89"}

22 / 27

23. REST API METHODSREST API METHODSREST API METHODSREST API METHODSREST API METHODSREST API METHODS
REST API METHODS
REST API METHODS
REST API METHODS
REST API METHODS
REST API METHODS
REST API METHODS
REST API METHODS
REST API METHODS
REST API METHODSREST API METHODS
GET
- Read a specific resource (by an identifier) or a
collection of resources.
PUT
- Update a specific resource (by an identifier) or a
collection of resources. Can also be used to create a
specific resource if the resource identifier is prior known.
DELETE
- Remove/delete a specific resource by an identifier.
POST
- Create a new resource. Also a catch-all verb for operations
that do not fit into the other categories.

23 / 27

24. SUCCESSSUCCESSSUCCESSSUCCESSSUCCESSSUCCESS
SUCCESS
SUCCESS
SUCCESS
SUCCESS
SUCCESS
SUCCESS
SUCCESS
SUCCESS
SUCCESSSUCCESS
200 OK
201 Created
202 Accepted
204 No Content
206 Partial Content

24 / 27

25. CLIENT SIDE ERRORCLIENT SIDE ERRORCLIENT SIDE ERRORCLIENT SIDE ERRORCLIENT SIDE ERRORCLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERROR
CLIENT SIDE ERRORCLIENT SIDE ERROR
400 Bad Request : {"error":"invalid_request",
"error_description":"There is no ‘purchase’ property"}
401 Unauthorized : {"error”:"no_credentials",
"error_description":"You must be authenticated"}
403 Forbidden : {"error":"protected_resource",
"error_description":"You need application cient rights"}
404 Not Found : {"error":"not_found",
"error_description": "The application ‘app_872’ does not exist"}
405 Method Not Allowed : {"error":"not_implemented",
"error_description":"Device creation not implemented"}
406 Not Acceptable : {"error": "not_acceptable",
"error_description":"Available languages: en, ja"}

25 / 27

26. SERVER SIDE ERRORSERVER SIDE ERRORSERVER SIDE ERRORSERVER SIDE ERRORSERVER SIDE ERRORSERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERROR
SERVER SIDE ERRORSERVER SIDE ERROR
500 Internal Server Error :
{"error":"server_error",
"error_description":"Oops! Something went wrong..."}
503 Service Unavailable :
{"error":"service_error",
"error_description":"Oops! Something went wrong..."}

26 / 27

27. Thank You

27 / 27