Building Better API’s

Mahmoud Zalt
Jul 30, 2017 · 22 min read

1. URL

/api/contacts GET Returns an array of contacts/api/contacts/:id GET Returns the contact with id of :id/api/contacts POST Adds a new contact and return it with an id attribute added/api/contacts/:id PUT Updates the contact with id of :id/api/contacts/:id PATCH Partially updates the contact with id of :id/api/contacts/:id DELETE Deletes the contact with id of :id/api/contacts/:id/star PUT Adds to favorites the contact with id of :id/api/contacts/:id/star DELETE Removes from favorites the contact with id of :id/api/contacts/:id/notes GET Returns the notes for the contact with id of :id/api/contacts/:id/notes/:nid GET Returns the note with id of :nid for the contact with id of :id/api/contacts/:id/notes POST Adds a new note for the contact with id of :id/api/contacts/:id/notes/:nid PUT Updates the note with id if :nid for the contact with id of :id/api/contacts/:id/notes/:nid PATCH Partially updates the note with id of :nid for the contact with id of :id/api/contacts/:id/notes/:nid DELETE Deletes the note with id of :nid for the contact with id of :id

2. Naming

3. Versioning

4. Responses

The Payload Format:

Content-Type: application/jsonAccept: application/json

The Payload Content:

POST /v1/animal HTTP/1.1Host: api.example.orgAccept: application/jsonContent-Type: application/jsonContent-Length: 24{   “something”: “Whatever”,   “type”: 315}
HTTP/1.1 200 OKDate: Mon, 00 Dec 2020 07:10:11 GMTContent-Type: application/jsonAccess-Control-Max-Age: 1728000Cache-Control: no-cache{   “status”: “success”,   “count”: 2,   “type”: “LoadServingEntity”,   “results”:[ {   “id”: 2756,   “name”:”Abou Talal”,}, {   “id”:2131,   “name”:”Insa Ya Foufi”,}]}

5. Headers

6. Errors

{   “http_code” : 500   “error_code” : 1234,   “message” : “Something bad happened”,   “description” : “More details about the error here”}

7. Parameters

/profile?fields=id,name,location

8. Pagination

‘paginator’ :{   ‘total_count’ : 100   ‘total_pages’ : 10   ‘current_page’ : 1   ‘limit’ : 10}

9. Documentation

10. Authentication

Token Based Authentication

JSON Web Tokens (JWT)

11. CROS

GET /cors HTTP/1.1Origin: http://api.zalt.meHost: api.mahmoudzalt.comAccept-Language: en-USConnection: keep-aliveUser-Agent: Mozilla/5.0…
Access-Control-Allow-Origin: *
Access-Control-Allow-Origin: http://api.zalt.meAccess-Control-Allow-Credentials: trueAccess-Control-Expose-Headers: FooBarContent-Type: text/html; charset=utf-8

12. SSL

13. Rate Limiting

14. Debugging / Testing

16. Date & Time

17. Hypermedia

18. Caching

19. Coding

20. Tips (Use existing frameworks)

Resources:


Mahmoud Zalt

Written by

★ Software Engineer & More! ★ http://zalt.me

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade