Entity List endpoint

The Entity List endpoint and fields are described below including details of the supported RESTful CRUD verbs. For details of the conventions of the API see the general conventions.

Endpoint path prefix: 

/n/v1/entitylist/

entitylist was introduced in API version V1

Entity List has not been marked for deprecation

Description

Entity list endpoint that is used for creating collections of entities e.g. for a blog listing.

The listed entity references are returned according to the sort order of the references
When duplicate sort order values are provided the specific ordering is undetermined
The list of entities is intended to be bounded to a reasonable number e.g. a collection size that would be sensible to post in bounded time. Practically this means the representation of the list would not typically exceed a few hundred KB. No restriction is currently enforced but as the list is not intended to be paged please consider this when constructing lists. For dynamic / calculated lists prefer searches.

Verbs / methods

This endpoint supports the following CRUD operations in line with our API conventions. See the conventions section for more details.

CREATE HTTP POST

Request payload

Entity List reference

{
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "name" : "/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c/entitylist/blog/",
  "entities" : [ {
    "entity" : {
      "urn" : "4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
      "url" : "/n/v1/entity/4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d"
    },
    "sortOrder" : 0
  } ]
}

Response payload

Entity List reference
Entity list for a collection of entity references. Note that the returned entity list on read will respect the natural ordering of the entity order sort order field

{
  "urn" : "661f12a5-a91e-4cb9-87ad-01ca1a07ffea",
  "url" : "/n/v1/entitylist/661f12a5-a91e-4cb9-87ad-01ca1a07ffea",
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "name" : "/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c/entitylist/blog/",
  "entities" : [ {
    "entity" : {
      "urn" : "4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
      "url" : "/n/v1/entity/4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d"
    },
    "sortOrder" : 0
  } ]
}

Response codes / scenarios

  • CREATE_SUCCESS

    API code CREATE_SUCCESS HTTP status code 201 : When the representation provided was successfully created return HTTP created (201). Note that when other context like authorisation and permissions are satisfied but the representation is invalid or missing required information typically a error representation with details of the missing information may be returned instead with REPRESENTATION_MISSING_REQUIRED_FIELD api error for example

  • REPRESENTATION_MISSING_REQUIRED_FIELD

    API code REPRESENTATION_MISSING_REQUIRED_FIELD HTTP status code 400 : When creating or updating a representation the provided representation was missing a required filed. Typically has a error response representation with details of the missing required field.

  • INVALID_REPRESENTATION

    API code INVALID_REPRESENTATION HTTP status code 400 : When creating or updating a representation and the provided representation is invalid. May include an error representation with details of the issue

READ HTTP GET

Response example

Entity List
Entity list for a collection of entity references. Note that the returned entity list on read will respect the natural ordering of the entity order sort order field

{
  "urn" : "661f12a5-a91e-4cb9-87ad-01ca1a07ffea",
  "url" : "/n/v1/entitylist/661f12a5-a91e-4cb9-87ad-01ca1a07ffea",
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "name" : "/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c/entitylist/blog/",
  "entities" : [ {
    "entity" : {
      "urn" : "4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
      "url" : "/n/v1/entity/4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d"
    },
    "sortOrder" : 0
  } ]
}

Response codes / scenarios

  • READ_SUCCESS

    API code READ_SUCCESS HTTP status code 200 : On read when the request is successful. The returned representation is given with the relevant 2XX HTTP code without further detail.

  • NOT_FOUND

    API code NOT_FOUND HTTP status code 404 : When the request referenced a representation or a concept that was not found including other request context requirements. Note that if a request is missing other concepts including authorisation, permissions or restrictions on the visibility HTTP not found (404) will typically be returned. Note that when creating a representation if the owner or other references can't be resolved the endpoint may return not found.

UPDATE HTTP PUT

Response example

Entity List
Entity list for a collection of entity references. Note that the returned entity list on read will respect the natural ordering of the entity order sort order field

{
  "urn" : "661f12a5-a91e-4cb9-87ad-01ca1a07ffea",
  "url" : "/n/v1/entitylist/661f12a5-a91e-4cb9-87ad-01ca1a07ffea",
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "name" : "/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c/entitylist/blog/",
  "entities" : [ {
    "entity" : {
      "urn" : "4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
      "url" : "/n/v1/entity/4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d"
    },
    "sortOrder" : 0
  } ]
}

Response codes / scenarios

  • UPDATE_SUCCESS

    API code UPDATE_SUCCESS HTTP status code 202 : When creation was successful and the representation was created. Returns HTTP accepted (202) response and typically includes the representation of the created representation for reference. Note that CREATE / UPDATE can trigger async operations after the representation is accepted which can update state.

  • NOT_FOUND

    API code NOT_FOUND HTTP status code 404 : When the request referenced a representation or a concept that was not found including other request context requirements. Note that if a request is missing other concepts including authorisation, permissions or restrictions on the visibility HTTP not found (404) will typically be returned. Note that when creating a representation if the owner or other references can't be resolved the endpoint may return not found.

  • REPRESENTATION_MISSING_REQUIRED_FIELD

    API code REPRESENTATION_MISSING_REQUIRED_FIELD HTTP status code 400 : When creating or updating a representation the provided representation was missing a required filed. Typically has a error response representation with details of the missing required field.

  • INVALID_REPRESENTATION

    API code INVALID_REPRESENTATION HTTP status code 400 : When creating or updating a representation and the provided representation is invalid. May include an error representation with details of the issue

DELETE HTTP DELETE

Response codes / scenarios

  • DELETE_SUCCESS

    API code DELETE_SUCCESS HTTP status code 202 : When deletion of a representation was successful. Note that returns HTTP accepted (202) to represent the success of the deletion state transfer rather than HTTP gone (410) as 4XX represent client errors for semantic consistency

  • NOT_FOUND

    API code NOT_FOUND HTTP status code 404 : When the request referenced a representation or a concept that was not found including other request context requirements. Note that if a request is missing other concepts including authorisation, permissions or restrictions on the visibility HTTP not found (404) will typically be returned. Note that when creating a representation if the owner or other references can't be resolved the endpoint may return not found.