Collection Operation (REST) Interface

The Collection class endeavors to handle much of the HTTP boilerplate code that you would typically have to implement to build an API. The following sections aim to clarify the behavior of Collection operations at the HTTP layer.

POST /<collection>

POST is one of the more interesting HTTP verbs in the context of a Carbon Collection. Unlike the rest of the HTTP verbs, POST is only allowed on the Collection URL (e.g., /<collection>) and not a Collection object URL (e.g. /<collection>/:<id>). Instead POSTing to the Collection supports both the insert and the insertObject operations (if enabled), routing the request to the appropriate handler based on the type of the body.

In the following tables, bulk will refer to requests whose body is an array and object will refer to requests whose body is a single object.

Request Parameters

Name	Request Type	Location	Description
body	bulk	body	An array of objects
body	object	body	An object

Response Headers

Name	Request Type	Description
Location	bulk	Contains the URL to retrieve all inserted objects in ID query format (see: FindConfig)
Location	object	Contains the object URL
idHeaderName	bulk	Contains the EJSON serialized IDs of the inserted objects
idHeaderName	object	Contains the EJSON serialized ID of the inserted object

Status Codes

Status	Request Type	Description
201	bulk	The objects were successfully inserted. The response body will contain the objects if configured.
201	object	The object was successfully inserted. The response body will contain the object if configured.
400	bulk and object	The request was malformed
403	bulk and object	The request is not authorized
500	bulk and object	There was an internal error processing the request

GET /<collection>

Request Parameters (note, <idParameterName> is configurable on Collection)

Name	Location	Description
<idParameterName>	query	Contains the IDs of objects to be retrieved. This parameter is only present if supportsIdQuery is true.
page	query	Contains the page number from which objects are to be retrieved. This parameter is only present if supportsPagination is true
pageSize	query	Specifies the number of objects per page. This is only present if supportsPagination is true. The default value for page size is configured using pageSize (note, if maxPageSize is specified, then the minimum of the two will be used)
skip	query	The number of objects in the Collection to skip before returning results
limit	query	The maximum number of objects to return in a result

Status Codes

Status	Description
200	The response body will contain a list of objects in the Collection subject to the parameters passed in the request
400	The request was malformed
403	The request is not authorized
500	There was an internal error processing the request

PUT /<collection>

Request Parameters

Name	Location	Description
body	body	A list of objects to replace to Collection

Status Codes

Status	Description
200	The Collection was successfully replaced. The new Collection will be returned in the response if returnsSavedObjects is true.
204	The Collection was successfully replaced. The response body will be empty if returnsSavedObjects is false.
400	The request was malformed
403	The request is not authorized
500	There was an internal error processing the request

PATCH /<collection>

Request Parameters

Name	Location	Description
update	body	An update spec
upsert	query	A boolean value indicating whether an upsert is desired. This parameter is only present if supportsUpsert is true.

Response Headers

Name	Description
Location	Contains the URL to retrieve all upserted objects in ID query format (see: FindConfig)
idHeaderName	Contains the EJSON serialized IDs of the upserted objects

Status Codes

Status	Description
200	Objects were successfully updated. The number of updated objects will be returned in the body.
201	Objects were successfully upserted. This is only possible if supportsUpsert is true. The number of updated objects will be returned if returnsUpsertedObjects is false, otherwise the objects will be returned in the response body.
400	The request was malformed
403	The request is not authorized
500	There was an internal error processing the request

DELETE /<collection>

Status Codes

Status	Description
200	Returns the list of objects removed in the response body if returnsRemovedObjects is true or the number of objects removed if not.
400	The request was malformed
403	The request is not authorized
500	There was an internal error processing the request

GET /<collection>/:<id>

Request Parameters (note, idPathParameterName is configurable on Collection)

Name	Location	Description
<idPathParameterName>	path	The ID component of the Collection object URL. Identifies a specific object in the Collection.

Status Codes

Status	Description
200	The response body will contain the object whose ID matches the value passed in <idPathParameterName>
400	The request was malformed
403	The request is not authorized
404	The object was not found
500	There was an internal error processing the request

PUT /<collection>/:<id>

Request Parameters (note, idPathParameterName is configurable on Collection)

Name	Location	Description
<idPathParameterName>	path	The ID component of the Collection object URL. Identifies a specific object in the Collection.
body	body	An object to save

Response Headers

Name	Description
Location	Contains the URL of the new object. Note, this is only possible if supportsUpsert is true.
idHeaderName	Contains the EJSON serialized ID of the new object. Note, this is only possible if supportsUpsert is true.

Status Codes

Status	Description
200	The response body will contain the saved object. This response code is only possible if returnsSavedObject is true.
201	This response code is only possible if supportsUpsert is true. If returnsSavedObject is true, the new object will be returned, otherwise the response body will be empty.
204	The response body will be empty. This response code is only possible if returnsSavedObject is false.
400	The request was malformed
403	The request is not authorized
404	The object was not found. This response code is only possible if supportsUpsert is false.
500	There was an internal error processing the request

PATCH /<collection>/:<id>

Request Parameters (note, idPathParameterName is configurable on Collection)

Name	Location	Description
<idPathParameterName>	path	The ID component of the Collection object URL. Identifies a specific object in the Collection.
update	body	An update spec
upsert	query	A boolean value indicating whether an upsert is desired. This parameter is only present if supportsUpsert is true.

Response Headers

Name	Description
Location	Contains the URL of the upserted object
idHeaderName	Contains the EJSON serialized ID of the upserted object

Status Codes

Status	Description
200	The object was successfully updated. The number of updated objects (1) will be returned in the body.
201	The object was successfully upserted. This is only possible if supportsUpsert is true. The number of updated objects (1) will be returned if returnsUpsertedObject is false, otherwise the object will be returned in the response body.
400	The request was malformed
403	The request is not authorized
404	The object was not found. This response code is only possible if supportsUpsert is false.
500	There was an internal error processing the request

DELETE /<collection>/:<id>

Request Parameters (note, idPathParameterName is configurable on Collection)

Name	Location	Description
<idPathParameterName>	path	The ID component of the Collection object URL. Identifies a specific object in the Collection.

Status Codes

Status	Description
200	The object was successfully removed. If returnsRemovedObject is true, the body will contain the object, otherwise the number of removed objects (1) will be returned.
400	The request was malformed
403	The request is not authorized
404	The object was not found
500	There was an internal error processing the request