LearnDay@Xoxzo is a monthly online seminar initiated by the Xoxzo team. We will have speakers from the team or guest speakers which will talk for 20 minutes each, on a subject of their choosing. "Build APIs You Won't Hate": thoughts on the book, presented by Fathur, Xoxzo Engineering XOXZO Learn Day #20 2020/06/26 ====================== We have recorded sessions of our previous LearnDay here: https://www.youtube.com/channel/UCiV-bQprArQxKBSzaKY1vQg For updates and news on our future LearnDays, follow us on Twitter (https://twitter.com/xoxzocom/) or sign up for our Exchange Newsletter (https://info.xoxzo.com/en/exchange-mailing-list/)

1. Building APIs you will
love
Stuff that I learn from reading `Building
APIs you won't hate` book and a little of
my input
Prepare by Fathur Rahman

2. Plural, Singular or Both naming?
GET /user or GET /users?
GET /user/1 or GET /users/1?
- Always use Plural for consistency.
- Dev don't need to guess whether GET /users will return a list of User,
- If GET /user will left the dev guessing will it return a single user or a list of
user
- Combining GET /users for list of user and GET /user/1 for single user is not
consistent

3. RESTful endpoints convention
- GET /places/
- GET /places/X
- GET /places/X,Y,Z
- GET /places/X/checkins
- GET /users/X/checkins
- GET /users/X/checkins/Y
Resources and subresources

4. Auto increment is devil
- Use UUID instead of ID for identification
- Imagine launching a massively anticipated
product, and the user can see the current
company_id is 2 only

5. Data relationship
1. Category 1 or author 1 doesn’t doesn’t contain enough info for
the API client
2. If client want to display category name, need extra API call.
Imagine 500 API call just to get category info for a Blog post
list page

6. Data relationship (cont)
Two strategies:
1. Relationship expanded by default
2. Relationship on-demand expand

7. Data relationship
1. Expanded by default
GET /users/1

8. Data relationship (cont)
2. On-demand expand
GET /users/1?expand=category

9. Response envelope
1. Always use data envelope so we can add extra metadata when needed
2. Example the response below, if we want to add list of expands available, it will
be weird if we add another key that doesn’t belongs to Blog post object

10. Response envelope (cont)
1. When using envelope, we can add any extra metadata that we need, without
actually modify the main response Object
2. If we are adding envelope when only we needed extra metadata, then the API
response structure is not consistent

11. Next, a little of my inputs as Front End
developer
Don't forget to check out the book!
https://apisyouwonthate.com/

12. POST vs PUT vs PATCH?
1. Use POST when creating a new record
2. Use PUT when you want to update a full object. Example update a Blog post
using form
3. Use PATCH when you want to update a part of the Object. Example update
only the title of blog post

13. POST vs PUT vs PATCH?
PUT
PATCH

14. Data consistency through all channels
- Sometimes, API dev transform the data for client consumption via Serializer /
Transformer
- Example below, url value is transform to include the host URL (http://test.com/)
- However, we forget to make it the data transform consistent through all channels, as
during development there is multiple way to access the data

15. API / Console / Unit Test
Console / Unit Test

16. Don't assume, but give options
- Example if we have API to return list of
categories
- There is category without parent, and
category with parent (subcategory)

17. Don't assume, but give options
- Provide filter key for the FE to
filter the data. Example
/categories?parent_only
- API should not assume that FE
only want parent category, and
doesn’t include the subcategory
in the response

18. Need to format the data? Time for
more endpoints
- For example, we want to get the
Categories response in Nested Tree
format
- It will be tempting to add key
/categories?format=tree

19. Need to format the data? Time for
more endpoints
- Don’t do this, as the response data structure is now
inconsistent. Original is array of Categories, now it return
Tree object
- We can have dedicated endpoints for this
Eg:
GET /treecategories

20. Sometimes, it’s good to assume
- For example, API can order list of data by default DESC,
since FE always interested with the latest data first
- Another example, to get list of post published this week, API
can provide filter key ?currweek_publish rather than FE
sending ?start_date and ?end_date
- This will save FE from writing the same logic at different
client (mobile / web / desktop)

21. Input param must be consistent
- Existing API using this input convention
- When API dev install new package, the package is expecting
input key in this format

22. Input param must be consistent
- It doesn’t make sense for the FE to use the new key
convention. FE doesnt need to know the Backend
implementation details
- BE need to map the key to follow existing convention which is
model_type and model_id. So all the API endpoints using
consistent input keys