1.
How to build simple yet
powerful API
@channaly

2.
What is an API?

3.
Is this an API?

4.
ob_start( );
ob_get_clean( );
ob_....

5.
What is an API?
We will cover API for client and server communication.

6.
Why API?
● Beyond browsers
● Mobile Apps
● Affiliates
● Microservices
● Information sharing

7.
How to API?
● Handling Request
● Handling Response
● Authentication and Authorization
● Protection
● Agile API ( TDD + CI/CD )
● Documentation
● Versioning

8.
What is a resource?
● Users
● Products
● Search preferences

9.
What is a resource?
An endpoint or Request uri is considered as a resource, for example
● /users
● /productions
● /my_preference

10.
Single Resource
● /me
● /my_preferences
Action HTTP Verb Endpoint
Create POST /my_preferences
Update PATCH /my_preferences
Delete DELETE /my_preferences
Read GET /my_preferences

11.
Multiple Resources
● /orders
● /products
Action HTTP Verb Endpoint
Create POST /products
Update PATCH /products/:id
Delete DELETE /products/:id
Read one single item GET /products/:id
Read a collection GET /products

12.
Multiple Resources - in user scope
● /my_orders
● /my_products
Action HTTP Verb Endpoint
Create POST /my_products
Update PATCH /my_products/:id
Delete DELETE /my_products/:id
Read One GET /my_products/:id
Read Collection GET /my_products

13.
Handling Request

14.
Use HTTP Verb correctly
● POST - To create a resource
● GET - To Query Read purpose
● PATCH - To Update partially
● PUT - To Update whole resource
● DELETE - To delete ( whether soft or hard delete)

15.
One Verb one Action

16.
Leverage HTTP Header for sensitive data
header(“Authorization: xyz”)
● Credential in URLs can be copied and shared by user with their
credentials embedded in them ( inadvertently)
● Most server will not write header logs
● URL most likely be logged in the server log

17.
Handle content-type request header
Content-Type: application/x-www-form-urlencoded
Content-Type: application/json; charset=utf-8

18.
Handling Response

19.
Send content type in response header
header(“Content-Type: application/json; charset=utf-8”)
● Most Http clients understand the header and decode response
payload to json

20.
Use Http status code correctly
● 201 Created
● 200 OK
● 204 No Content
● 400 Bad Request
● 401 Unauthorized
● 403 Forbidden
● 404 Not found
● 422 Unprocessable
● 429 Too Many Request

21.
Http status code vs response body error?
● Status code is necessary to user auth and permission, a best place to
handle error.
● The response body should be tested to verify the app sending or
generating the right content. It is not for error handling.
● Request status should be a symbolic representation(integer 2xx) rather
than a free text ( issue with language and translation )
● Free text tends to be misunderstood, lack of standardization

22.
Http status code vs response body error?

23.
Content type
- text/html
- text/html; charset=UTF-8

24.
Content type ( continue ... )
Desktop
- Image.png is a png file Open with Photoshop
- Image.dat how come I know the format
Web
- /users.json
- render json: users # users string in json format along with application/json content type.
- Client ( server ) parse the content accordingly

25.
Authentication and Authorization

26.
Send user/pwd for every request
● GET /orders?user=x&pwd=yeiqkwhw
● Server authenticate and check if user x has access

27.
A bit of refactoring

28.
Exchange for token
● Exchange your credential for a temporary access token
POST /auth user: ‘x’, pwd: ‘y’
{ token: ‘12wh7269kvxz2vpouem8337230f3y’ }
GET /products

29.
Token Expiration
● When to expire
{ token: ‘17fab162728’, expires_in: ‘10days’ }
● What to do when it is expires ( force user to login again or store user
credential and then login again behind the scene)
● { token: ‘17fab162728’, refresh_token: ‘abf380917fab162728’ … }

30.
What happens if some api not related to user
- Forget Password
- Confirm mobile number before login
The resources above are not related to resource owner but you still want to
limit access from public

31.
Resource without owner
- Client API_KEY and API_SECRET as credentials
- Exchange API KEY and API SECRET for access token
POST /auth {client_id: ‘clientx’, client_secret: ‘magic secret’ }

32.
Exchange for token
- POST /auth is getting complicated with very diff params
- This endpoint mainly for generating token
- Need a symbolic value to Identify the action
POST /auth { user: ‘x’, pwd: ‘y’, type:’user_login’ }
POST /auth {client_id: ‘client_x’, client_scret: ‘client_y’, type: ‘app_login’ }

33.
Problem?
- Who will be able to use auth type ‘user_login’?
- Who can access user info?
- The authorization server need to generate a token representing a level
of access to a client app.
POST /auth { client_id: ‘x’, client_secret: ‘y’, type: ‘authorization’ }

34.
A bit more standardized
● Oauth2 Protocol.
● Token generation API JWT
● Take into account all the points mentioned above and more
● More features that you have never thought of but you need them
● Standardize
● Most people implement this in their favourite framework
● https://github.com/lucadegasperi/oauth2-server-laravel d45, c522, s2k
● https://github.com/doorkeeper-gem/doorkeeper d160, c1470, s3k

35.
Protect API from abusive clients
● Filter request parameter appropriately.
● Paginate result
● Consider allow those IPs in your whitelist
● Completely deny those from blacklist
● Limit Access rate
● Bandwidth throttling ( WAF )

36.
Automate testing / CI/CD

37.
Why employ automate test?
1. A user enters his phone number
2. The APP connects to the API to request server to send pincode
3. The APP display the verification code screen
4. The user has to wait for the message to arrive
5. The user enter the pin code
6. The APP verify the pin code
7. The APP receive the secret verification token
8. The APP sends to create a user with a secret verification token

38.
Versioning
● API Namespacing and versioning /api/v1, partners/api/v2
● Cache with Memcached or Redis
● Using enum in for example status = 0, 1, 2

39.
Documenting your API
● Request endpoints with HTTP verb
● Describe request params name with their purposes and data type
● Mandatory ( required , optional )
● Example of request and response payload with full http header and
status code
● Describe response params name along with their meanings
● Business flow and interaction diagram
● Use simulator for quick API test.

40.
API Doc auto generating tools
- https://github.com/zircote/swagger-php
- https://github.com/zipmark/rspec_api_documentation
- https://www.postman.com/ Powerful API collection, env, sample
response, and publish doc )

41.
Try it yourself
● https://www.slideshare.net/ChannaLychannaly/how-to-build-
simple-yet-powerful-apipptx