Important

You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Available HTTP Methods

The primary or most commonly-used HTTP methods are POST, GET, PUT, PATCH, and DELETE. These methods correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other methods, too, but they are utilized less frequently.

Below is a table summarizing HTTP methods available in Oro API and their return values in combination with the resource URIs:

HTTP Method

CRUD operation

Entire Collection (e.g. /users)

Specific Item (e.g. /users/{id})

GET

Read

200 (OK), list of entities. Use pagination, sorting and filtering to navigate big lists.

200 (OK), single entity.

404 (Not Found), if ID not found or invalid.

POST

Create

201 (Created), Response contains response similar to GET /user/{id} containing new ID.

not applicable

PATCH

Update

Batch API

200 (OK) or 204 (No Content).

404 (Not Found), if ID not found or invalid.

DELETE

Delete

204 (No Content).

400(Bad Request) if no filter is specified.

204 (No Content).

404 (Not Found), if ID not found or invalid.

PUT

Update/Replace

not implemented

not implemented

Also, the HTTP methods can be classified by the idempotent and safe properties.

The safe methods are the HTTP methods that do not modify resources. For instance, using GET or HEAD on a resource URL, should NEVER change the resource.

An idempotent HTTP method is an HTTP method that can be called many times without different outcomes. It would not matter if the method is called only once, or ten times over. The result should be the same. For more details, please see RFC 7231: Common Method Properties.

Below is a table summarizing HTTP methods by its idempotency and safety:

HTTP Method

Idempotent

Safe

OPTIONS

yes

yes

GET

yes

yes

HEAD

yes

yes

PUT

yes

no

POST

no

no

DELETE

yes

no

PATCH

no

no

Business Tip

Researching B2B eCommerce platforms? Explore our platform comparison guide to help you make an informed decision.

GET

The HTTP GET method is used to read (or retrieve) a representation of a resource. In case of success (or non-error), GET returns a representation in JSON and an HTTP response status code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST).

Note

According to the design of the HTTP specification, GET requests are used only to read data and not change it. So, they are considered safe. That is they can be called without risk of data modification or corruption—calling it once has the same effect as calling it 10 times.

POST

The POST method is most often utilized to create new resources. In particular, it is used to create subordinate resources. That is subordinate to some other (e.g. parent) resource. In other words, when creating a new resource, POST to the parent and the service takes care of associating the new resource with the parent, assigning an ID (new resource URI), etc.

On successful creation, HTTP response code 201 is returned.

Caution

POST is not a safe operation. Making two identical POST requests will most likely result in two resources containing the same information but with different identifiers.

Note

It is possible to create both primary and related API resources via a single API request. For details, see the Creating and Updating Related Resources with Primary API Resource section.

PATCH

PATCH is used to modify resources. The PATCH request only needs to contain the changes to the resource, not the complete resource.

In other words, the body should contain a set of instructions describing how a resource currently residing on the server should be modified to produce a new version.

Caution

PATCH is not a safe operation. Collisions from multiple PATCH requests may be dangerous because some patch formats need to operate from a known base point; otherwise, they will corrupt the resource. Clients using this kind of patch application should use a conditional request (e.g., GET a resource, ensure it was not modified and apply PATCH) such that the request will fail if the resource has been updated since the client last accessed the resource.

DELETE

DELETE is quite easy to understand. It is used to delete a resource identified by filters or ID.

On successful deletion, the HTTP response status code 204 (No Content) returns with no response body.

Important

If you DELETE a resource, it is removed. Repeatedly calling DELETE on that resource will often return a 404 (NOT FOUND) status code since it was already removed and, therefore, is no longer findable.