CRUD Operations

Semantics of Operations on Persistent Objects (Resources)

CRUD is the shortcut of the four basic operations you can perform on a specified resource (persistent storage object):

• C REATE a resource (collection or entity); if an entity is created it's added to a collection
• R EAD a resource (collection or entity)
• U PDATE a resource (collection or entity)
• D ELETE a resource (collection or entity); if a collection is deleted, all containing entities are also deleted

This is comparable to a database, where the four basic data manipulation operations are SELECT (read), INSERT (create), UPDATE, and DELETE.

HTTP Methods in API Requests

When it comes to API requests, one part of the request is the HTTP method. Basically we allow the following HTTP methods to be performed on a single resource via the API:

• GET
• POST
• PUT
• DELETE

Additionally we allow OPTIONS requests on all resources without exceptions. These OPTIONS requests return bodiless responses with a header, showing you which other HTTP methods are allowed on that resource:

Access-Control-Allow-Methods: GET, OPTIONS

This means you can only perform OPTIONS and GET requests on that resource.

How Everything Comes Together

Now, any of the four HTTP methods have a counterpart from the CRUD operations, as well as database operations. To show you how everything is working together, we take the Wants List example where all four operations are possible:

CRUD Operation	HTTP Method	Wants List Example	Description
READ	GET	GET /wantslist	Returns a collection of wants lists for the authenticated user.
		GET /wantslist/1	Returns a single wants list entity for the authenticated user specified by the ID (1) of the wants list.
CREATE	POST	POST /wantslist request body	Creates a new wants list entity for the authenticated user; returns the newly created wants list entity. Note: POST requests with providing an ID in the URI are not possible, because an ID is automatically assigned to the new entity.
UPDATE	PUT	PUT /wantslist/1 request body	Updates a single wants list entity for the authenticated user specified by the ID (1) of the wants list; returns the newly created wants list entity. Note: PUT requests without an ID in the URI are not possible, because you can only perform update operations on a single entity, not the whole collection.
DELETE	DELETE	DELETE /wantslist/1	Deletes a single wants list entity for the authenticated user specified by the ID (1) of the wants list; returns a bodiless 200 OK HTTP status response. Note: PUT requests without an ID in the URI are not possible, because we do not allow the deleting your whole wants list collection at once.