The Nitty Gritty of API Methods

I have always had a sweet tooth, which I partly blame on my late grandfather, Nyanya. I used to enjoy the walks and drives we took when I was younger to the different candy stores looking for new candy to try as he told me stories of the olden days and how things have changed for the better, and how proud he was of how the town grew in terms of resources and infrastructure. We had a particular store that we always saved for last because the owner, Lucy, was a good friend of my grandpa. Lucy was so kind and always saved the best sweets for me. I used to get the optimal customer service treatment. This one time I wanted our usual order of red berry sweets, but there were not any at the time, and she recommended another treat, which was sweet and sour. I was skeptical, but I trusted Lucy since she was our longtime sweets plug, and if she recommends something, it's obviously top-notch.

The goal of this article is to explore the different API (application programming interface) methods there are. But before the deep dive, we need to start from the top. An API is an interface between the client and the server. Case in point: my grandad and I are the clients since we want to get sweets from Lucy's shop. Lucy is the API, and the shop is her server. When we wanted our usual order, she responded by telling us that they were not available and recommended a particular type of sweet. In software development, an API gets a request from a client and provides a response through status codes like 404 if the resource is not available or 200 if the resource is available. But to know what response to give and how to interact—that is, the exchange of knowing what to ask for and how to interact—is what we are referring to as API methods.

API methods are specific HTTP methods that interact with resources on a server through an API. The common API methods are GET, POST, PUT, PATCH, and DELETE.

GET

The GET method is used to acquire data from the server without making any adjustments to it. The GET requests are read-only and should not have ramifications on the server. GET requests should be safe and idempotent, which means that the same requests should obtain the same result without altering the server.

POST

The POST method is used to send data to the server to make a new resource. POST is typically used to convey data to the server for processing or add brand-new records to a collection. POST requests are idempotent because they will affect the server directly, which means that every POST request will result in a new resource being created on the server.

PUT

PUT is used to replace or update an existing resource on the server. PUT conveys the representation of the resource, and the server replaces it with the data provided.

PUT is idempotent since multiple PUT requests have the same effect as one request. However, if the request does not exist, the server will create one based on the data.

PATCH

PATCH is a method that updates partial information on an existing resource. Sort of like how an edit button works, make a few changes, say a spelling mistake in a word of a sentence, but the rest of the sentence remains the same.

DELETE

DELETE is used to remove a specified resource permanently from the server. DELETE is not idempotent since it eradicates a resource from a server.

Differences Between PUT and PATCH

A common question asked when interacting with API methods is what are the key differences between PUT and PATCH. They are so similar yet so different.

The PUT method is used to replace a whole resource. To clarify, we have a product resource with a name, price, and description. To replace the entire resource, we would have to change the information on all the fields (name, price, and description) that are going to be sent as a request.

The PATCH method updates specific parts of the resource. Using the same example, we have a product resource with a name, price, and description. For PATCH, we can update the description and add information to that field. If the description was "plain purple sweater" we can update it to "purple sweater with white lace on the front".

PUT is idempotent, meaning calling it a couple of times with the same data has the same effect as calling it once, while PATCH is not idempotent, so calling it with the same data may yield unexpected results.

PUT is used to create or update a resource, while PATCH is used to update resources.

The differences come up depending on the use case, control level, and efficiency. If you need to replace the entirety of a resource, use PUT; if you want to modify the data without overwriting the existing resource, use PATCH.

Best Practices of API Methods

GET

• Use GET to perform operations that can only be read and  do not affect the server.
• Make use of query parameters such as sorting, filtering, and paginating the responses for easy access.
• Adapt caching mechanisms like ETag and Last-Modified to reduce the server load and improve the response time for requests made repeatedly.

POST

• Use POST to create new resources on the server.
• Have a clear illustration of the request payload format and structure of the resource that is created in the response.
• The new resource added should have a unique identifier for ease of access.
• Ensure that the requests are not idempotent.

PUT

• Replace a whole resource on the server using PUT.
• Have the complete resource with required fields so that if some fields are not provided, they should be set or reset to default values.
• Ensure the PUT request is idempotent.
• Adapt versioning to handle updates to resources without breaking compatibility with older users.

PATCH

• For partial updates to an existing resource, use PATCH.
• Define the format clearly and concisely for the PATCH requests and have the supported operations documented.
• Ensure the server applies the partial changes correctly, leaving the untouched attributes unchanged.

DELETE

• Use DELETE to eradicate a resource
• Have authentication and authorisation mechanisms in place to prevent eradication of resources by unauthorised persons
• Return proper HTTP status codes
• Ensure DELETE requests are not idempotent

In conclusion, API methods play a fundamental role in enabling seamless communication and interaction between different software components in web development. Each method serves specific functions and has distinct characteristics, allowing developers to perform a wide range of operations on resources. As software continues to evolve, API methods will be at the forefront of driving the future of interconnected software ecosystems.