1. API design
concepts
1
By: Anas Jamil
linkedin.com/in/anasjamil
[Jan 2017]

2. Contents
1- What is an API?
2- What is API design?
3- Consumer-oriented API design.
4- API design and development approach.
5- API Description languages.
6- Introduction to REST.
7- RAML for API frontend design.
2

3. 1- What is an API?
3
Application programming interface.
- It's a set of clearly defined methods of communication between various software components ( or services).
Why?!
- Web 3.0 .
- It is a product.
- Application Programming eXperience (APX).

4. 2- What is API design?
4
Any type of design needs well-informed decisions :
1- Architectural design decisions.
2- Front-end design decisions.
3- Back-end design decisions.
4- Non-functional design decisions.

5. 2- What is API design?
5
What is the difference between API design & API
architecture?
- API design is one aspect of api architecture
- API client (like mobile app).
Why API design is important?
Changes are difficult when it is ready (live).

6. 3- Consumer-oriented API design.
6
How to put api design into practice?
1 - Is it sport or van?
2 - Is it hybrid or electric ? ( Architectural style)
3 - Create blueprint of car.
4 - Simulate car component and collect feedback
5 - Put all components together.

7. 3- Consumer-oriented API design.
How to put api design into practice?
1- How the majority of users would want to use the new API? mobile app?
Software?
2- Rest OR SOAP (Architectural style)?
3- Design blueprint of the API using RAML.
4- Build prototype of api and collect feedback.
5- Use RAML to generate API.
7

8. 4- API design and development
approach.
8
1- Inside-out approach.
2- Outside-in approach (Consumer oriented).
3- Contract-first approach.
4- Agile design approach
5- Simulation design approach (Time to market).

9. 5- API Description languages.
9
- Originally used for the description of the API, but it can be used for building the API with automated
tools like OpenAPI, RAML.
- Create single source of truth and main reference of API designer and developer.
- Describe "What" instead of "Who", Like "What is the structure of response" instead of "who the
response is computed".
- Used to build the API and the client of API.
- Used as contract between API provider & API consumer.

10. 5- API Description languages.
10
Responsibilities of APIs:
1 Gathering data.
1 Format data.
1 Delivering data from backend.
1 Securing data (do authentication).

11. 5- API Description languages.
11
Properties of API:
1 Simple: easy to learn and easy to use.
1 Clean: like , name of parameters is understandable.
1 Clear: Only one thing.
1 Forgiving compatible: provide hints for fixing mistakes and handle unexpected
input.

12. 6- Introduction to REST.
12
Representational state transfer
- REST is not standard.
- REST is not protocol.
- REST is architectural style. consisting of architectural constraints and agreements
(HTTP).
HTTP :
- Hypertext Transfer Protocol
- HTTP is the foundation of data communication for the World Wide Web.

13. 6- Introduction to REST.
13
Some basic HTTP terminology:
1 Resource.
1 Representation.
1 Uniform HTTP Interface.
1 Uniform Resource identifier (URI)

14. 7- RAML for API frontend design.
14
RESTful API Modeling Language
- Based on YAML
- Human and machine readable.
- Used to generate documentation and api
skeleton.

15. 15

16. 16

17. 17
References:
RESTful API Design (API-University Series), Matthias Biehl
[Nov 2016]