An api is really an interesting thing, because it allows you to do the work once, and have its effect (result) be replicated ad infinitum. Consider the way the cursor works in WoW. The cursor points over something, and somehow it knows what it is hovering over. Well, For a mouse to able to locate something in that sense, it has to have the coordinates of the item (ex. a chest). If the coordinates that you are hovering over match the coordinates of the chest, then you know you are hovering over the chest. The function to determine this is complex, but it is at the end of the day reducible to a function. We can still walk away with an atomic piece that can be transported anywhere. So imagine we take the functionality of determining where the coorinate of the cursor is and wrap it up into a function. Now all we need to do is run that function every time the mouse moves. We have just created an API that easily replicable across the entire application.
we can make a simplifying assumption in the case of dataflow through an API: it is reasonable to assume that all the servers will be updated first, and all the clients second. Thus, you only need backward compatibility on requests, and forward compatibility on responses.
The API is client-facing. Therefore, any questions about what an API endpoint does should ultimately fall back to the user's expectations.
- ex. soft-delete is a common implementation, where a column on a database item called
isDeletedis simply switched to
true, rather than actually removing an item from a table. From an API design standpoint, the question then becomes "which http method is this, a DELETE request, or PATCH request?". If a DELETE request is for deleting resources, then surely we'd want to use a PATCH request. However, the logic is that the API hides implementation details behind its interface. The implementation of a soft-delete is of no importance to the client using the API, therefore none of the interface should reflect any kind of implementation details. A DELETE http request is the right choice here because of this.
Robustness principle (Postel's law)
"be conservative (strict) in what you send, be liberal in what you accept"
- programs that send messages to other machines (or to other programs on the same machine) should conform completely to the specifications, but programs that receive messages should accept non-conformant input as long as the meaning is clear.
difference between API and SDK