Skip to content

description: >- This chapter explores REST API CRUD operations using HTTP methods (GET, PUT, POST, PATCH, DELETE), ensuring effective resource manipulation.

Methods

CRUD Operations with REST APIs

In the world of web development, APIs (Application Programming Interfaces) play a crucial role in enabling communication between different software systems. REST (Representational State Transfer) is a widely adopted architectural style for designing networked applications. One of the key aspects of RESTful APIs is the use of HTTP methods to perform various operations on resources. In this chapter, we will explore the common HTTP methods: GET, PUT, POST, PATCH, and DELETE.

GET: Retrieving Data

The GET method is used to retrieve data from a specified resource. When a client makes a GET request to a RESTful API, it is asking the server to return the current state of the resource or a collection of resources. This operation is read-only and does not modify the resource.

GET Request Example:

GET /api/users/123

GET Response Example:

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "created_at": "2023-01-01T12:34:56Z",
  "updated_at": "2023-11-30T15:45:00Z"
}

Searching with GET

When making GET calls to repositories, common patterns for filtering and searching enhance data retrieval. Query parameters are often utilized to specify conditions. For instance, to retrieve users with a specific role, a GET request might look like GET /api/users?role=admin. Similarly, searching for users with a certain name could involve GET /api/users?name=John. These patterns allow developers to tailor GET requests, obtaining precisely the data needed from the repository.

Alumio's HTTP Transformer with GET

Alumio treats a GET differently than the other methods. A HTTP Transformer, Subscriber or Publisher has a "Request Parameters" field. For all other methods, the "Request Parameters" field is used as the body of the request. However, for GET calls this is treated as part of the URL. This is generally used to be able to write JSON to write complex queries/searches, while encoding that JSON into the URL when actually sending the request.

POST: Creating Data

The POST method is used to submit data to be processed to a specified resource. It often results in the creation of a new resource based on the information provided in the request body.

It really depends on the provider of the API how it functions. Generally, it is one of these options:

  • POST is only allowed to create a resource. If you try to send a POST for an already existing object, it will send you an error back.
  • You are allowed to always send a POST - if the resouce already exists, it updates it.

When compared to a PUT, generally the main difference is that a POST should contain the entire resource that you want to create.

Note that some systems will 'reset' attributes to default if you update a resource using POST. So the system might change more than just what you've sent.

POST Request Example:

POST /api/users

{
  "name": "New User",
  "email": "new.user@example.com"
}

PUT: Updating Data

The PUT method is employed to update a resource or create it if it does not exist. When a client sends a PUT request, it can, but not necessarily, includes the full representation of the resource in the request body. The server then updates the resource with this new representation.

It really depends on the provider of the API how it functions. Generally, it is one of these options:

  • PUT is not allowed to create a resource. You can only use POST to create the resource, and only use PUT to update the resource
  • You are allowed to always send a PUT - if the resource does not exist, it is created. If it does, the resource is updated.

The updating behaviour of PUT also depends on the provider of the API. These two options have been seen in the wild:

  • The current representation of the object is merged with the update you sent. This way, a PUT is truly an update: if you send just a name field, you'll only update the name and not the email field. Required attributes are not required in the update, since the current object should also include those attributes.
  • The current representation of the object is completely replaced by the update. This means that no data of the current object is retained. Required attributes are in this case also required within a PUT.

Note that some systems will 'reset' attributes to default if you update a resource using POST. So the system might change more than just what you've sent.

Note 2: updating an array within the resource will generally lead to completely replacing the array. If you need to 'merge' with the current array (for example, when adding pricelists to a customers), you should first do a GET, merge the array with the one you want to add and send the entire array through.

PUT Request Example:

PUT /api/users/123

{
  "name": "Updated Name",
  "email": "updated.email@example.com"
}

PATCH: Partially Updating Data

The PATCH method is similar to PUT but is used for partial updates to a resource. Instead of sending the entire updated representation, the client only includes the changes to be applied. This can be beneficial when updating large resources to reduce the amount of data sent over the network. Also, if you have several routes updating a single resource, they are not aware of the entire resource.

If a PATCH is possible, it should mean that only the data sent is changed.

PATCH Request Example:

PATCH /api/users/123

{
  "email": "updated.email@example.com"
}

DELETE: Removing Data

The DELETE method is used to request the removal of a resource. When a client sends a DELETE request, it is asking the server to delete the specified resource.

DELETE Request Example:

DELETE /api/users/123

Read more about RESTful API's here: https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/