CST - Cyber Sapient’s Post

View organization page for CST - Cyber Sapient, graphic

30,954 followers

𝗕𝗲𝘀𝘁 𝗣𝗿𝗮𝗰𝘁𝗶𝗰𝗲𝘀 𝗶𝗻 𝗔𝗣𝗜 𝗗𝗲𝘀𝗶𝗴𝗻 A well-defined API should be easy to work with, concise, and hard to misuse. Here are some general recommendations: 𝟭. 𝗨𝘀𝗲 𝗻𝗼𝘂𝗻𝘀 𝗶𝗻𝘀𝘁𝗲𝗮𝗱 𝗼𝗳 𝘃𝗲𝗿𝗯𝘀 Verbs should not be used in endpoint paths. Instead, the pathname should contain the nouns that identify the object to which the endpoint we are accessing or altering belongs. E.g., instead of using /𝚐𝚎𝚝𝙰𝚕𝚕𝙲𝚕𝚒𝚎𝚗𝚝𝚜 to fetch all clients, use /𝚌𝚕𝚒𝚎𝚗𝚝𝚜. 𝟮. 𝗨𝘀𝗲 𝗽𝗹𝘂𝗿𝗮𝗹 𝗿𝗲𝘀𝗼𝘂𝗿𝗰𝗲 𝗻𝗼𝘂𝗻𝘀 Use the plural form for resource nouns because this fits all types of endpoints. E.g., instead of using /𝚎𝚖𝚙𝚕𝚘𝚢𝚎𝚎/:𝚒𝚍/, use /𝚎𝚖𝚙𝚕𝚘𝚢𝚎𝚎𝚜/:𝚒𝚍/ 𝟯. 𝗕𝗲 𝗰𝗼𝗻𝘀𝗶𝘀𝘁𝗲𝗻𝘁 When we say to be consistent, this means to be predictable. When we have one endpoint defined, others should behave similarly. So, use the same case for resources, and the same auth methods for all endpoints, headers, status codes, etc. 𝟰. 𝗞𝗲𝗲𝗽 𝗶𝘁 𝘀𝗶𝗺𝗽𝗹𝗲 We should make naming all endpoints to be resource-oriented, as they are. If we want to define an API for users, we would describe it as: /𝚞𝚜𝚎𝚛𝚜 /𝚞𝚜𝚎𝚛𝚜/𝟷𝟸𝟺 So, the first API gets all users, and the second one gets a specific user. 𝟱. 𝗨𝘀𝗲 𝗽𝗿𝗼𝗽𝗲𝗿 𝘀𝘁𝗮𝘁𝘂𝘀 𝗰𝗼𝗱𝗲𝘀 This one is super important. There are many HTTP status codes, but we usually use just some. Don't use too many, but use the same status codes for the same outcomes across the API, e.g., - 200 for general sucess - 201 for succesfull creation - 400 for bad requests - 401 for unauthorized requests - 403 for missing permissions - 404 for missing resources - 5xx for internal errors 𝟲. 𝗗𝗼𝗻'𝘁 𝗿𝗲𝘁𝘂𝗿𝗻 𝗽𝗹𝗮𝗶𝗻 𝘁𝗲𝘅𝘁 REST APIs should accept JSON for request payload and respond with JSON because it is a standard for transferring data. Yet, more is needed to return a body with JSON-formatted string; we need to specify a Content-Type header to be application/json. 𝟳. 𝗗𝗼 𝗽𝗿𝗼𝗽𝗲𝗿 𝗲𝗿𝗿𝗼𝗿 𝗵𝗮𝗻𝗱𝗹𝗶𝗻𝗴 Eliminate confusion when an error occurs, so we must handle errors properly and return a response code that indicates what happened (from 400 to 5xx errors). 𝟴. 𝗛𝗮𝘃𝗲 𝗴𝗼𝗼𝗱 𝘀𝗲𝗰𝘂𝗿𝗶𝘁𝘆 𝗽𝗿𝗮𝗰𝘁𝗶𝗰𝗲𝘀 Protect all communication between a client and a server. It means that we need to use SSL/TLS all the time, with no exceptions. Also, allow auth via API keys, which should be passed using a custom HTTP header with an expiration day. 𝟵. 𝗨𝘀𝗲 𝗽𝗮𝗴𝗶𝗻𝗮𝘁𝗶𝗼𝗻 Use pagination if our API needs to return many data, as this will make our API future-proof. Use page and page_size is recommended here. E.g., /𝚙𝚛𝚘𝚍𝚞𝚌𝚝𝚜?𝚙𝚊𝚐𝚎=𝟷0&𝚙𝚊𝚐𝚎_𝚜𝚒𝚣𝚎=𝟸0 𝟭𝟬. 𝗩𝗲𝗿𝘀𝗶𝗼𝗻𝗶𝗻𝗴 It is important to version APIs from the first version, as our APIs could have different users. #api

  • No alternative text description for this image

To view or add a comment, sign in

Explore topics