CRUD - Create Read Update Delete - Operations

This section provides details on Create Read Update Delete (CRUD) operations on resources.

• Introduction
• Create a Resource
• Read Resources
  • Read a Resource Collection
  • Read a Single Resource
• Update a Single Resource
• Delete a Single Resource
• Resource Collection Operations

Introduction

REST is a resource oriented pattern where a business object is represented as a resource that is addressable by a URL.

Specific urls are used to manage the CRUD life cycle of a resource where the operation and path define a standard mechanism for creating, reading, updating, and deleting a resource. The standard set of CRUD operations is shown in the following table:

A complete CRUD sample API document is provided as a template here CRUD Sample. To see the sample API, copy the raw API into the Swagger editor.

The remainder of this section describes each of the CRUD operations.

Create a Resource

The following HTTP operation and path are used to create a single resource in a system:

• POST /resources/

The resource definition is contained in the POST payload although the payload may be empty for specific use cases.

The POST path does not contain a resource identifier (resourceId) because the system receiving the resource definition generates a resourceId for the created object.

There are use cases where the resourceId is provided as an externally generated resource identifier in the resource payload of the POST operation. This approach is not a recommended pattern because RESTful HTTP APIs should be unaware of the client and a mechanism must be introduced to ensure that different clients provide unique resource identifiers.

The following lists the standards when creating a resource:

Read Resources

There are two REST paths to define read operations in a CRUD model:

Read a Resource Collection

The following HTTP operation and path are used to read (or list) all resources in a system:

• GET /resources/

This operation will return an array of objects wrapped up within an object as shown in the following example.

The array name must be called either items or the plural resource name e.g. accounts for GET /accounts.

{
  "items": [   # or accounts
    {
      "accountId": "0001123467001",
      "name": "Current GBP",
      "uri": "/accounts/0001123467001"
    },
    {
      "accountId": "0001123467002",
      "name": "Current EUR",
      "uri": "/accounts/0001123467002"
    },
    {
      "accountId": "0001123467003",
      "name": "Current USD",
      "uri": "/accounts/0001123467003"
    }
  ]
}

Each resource object within a collection can contain either the resource identifier, a partial view of the resource, or the complete resource.

When the number of resources returned in the collection is large, pagination and filtering should be implemented - for more information see Collections and Pagination

When no resources are returned in a collection, either because the filtering applied is too restrictive or because no resources exist then the response must return a 200 with an empty array, a 404 response is not appropriate.

A GET request only allows path and query parameters which will be visible in the url, hence, searching personally identifiable information (PII) such as a social security number using GET is usually prohibited by the Security Officer. In these cases a POST can be used with the PII data passed in the payload body e.g. ‘POST /resources/search’ {“ssn”: “122223”}`.

The following lists the standards when reading a resource collection:

Read a Single Resource

The following HTTP operation and path are used to read a single resource in a system:

• GET /resources/{resourceId}

The following lists the standards when reading a single resource:

Update a Single Resource

Once a resource is created it may be useful to update it, for example, to add or remove additional optional field details or to change mandatory fields such as status.

The following HTTP operation and path are used to update a single resource in a system:

• PUT /resources/{resourceId} - to update the entire resource
• PATCH /resources/{resourceId} - to update a part of a resource

For further information on PATCH see this section.

When updating a resource full consideration must be given to concurrency issues - for further information see this section.

Note that read only fields cannot be updated, for example, the resourceId is immutable.

The following lists the standards when updating a resource:

Delete a Single Resource

The following HTTP operation and path are used to delete a single resource in a system:

• DELETE /resources/{resourceId}

DELETE can be used to delete, or cancel, or close a resource or a session. Once a DELETE has taken place, a subsequent GET with the given resource identifier should return a 404.

When deleting a resource full consideration must be given to concurrency issues - for further information see this section.

The following lists the standards when updating a resource:

Resource Collection Operations

The only operation that handles resource collections in a standard CRUD model is GET /resources.

There is no standard pattern for creating, updating or deleting resource collections using a single client HTTP call and it is recommended that additional endpoints beyond GET for supporting resource collections are not provided because the update of multiple resources is not typically an atomic operation and error management becomes complex when, for example, most resources are updated but some resources failed to update.

The following lists the standards for handling resource collections: