External API Series Service REST Documentation

GET /{seriesId}
GET /
GET /{seriesId}/acl
GET /{seriesId}/metadata
GET /{seriesId}/properties
GET /series.json
POST /
DELETE /{seriesId}
DELETE /{seriesId}/metadata
PUT /{seriesId}
PUT /{seriesId}/acl
PUT /{seriesId}/metadata
PUT /{seriesId}/properties

Read methods

Method / Path: GET /{seriesId}

Description: Returns a single series.

Path params: seriesId: The series id

Optional (query) params: withacl: Whether the acl should be included in the response.

Response formats: application/json
application/v1.0.0+json
application/v1.1.0+json
application/v1.2.0+json
application/v1.3.0+json
application/v1.4.0+json
application/v1.5.0+json
application/v1.6.0+json
application/v1.7.0+json
application/v1.8.0+json
application/v1.9.0+json
application/v1.10.0+json
application/v1.11.0+json

Status codes: 200: OK, The series is returned.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}?withacl={withacl}

Testing form (click to reveal)

Method / Path: GET /

Description: Returns a list of series.

Path params: NONE

Optional (query) params: onlyWithWriteAccess: Whether only to get the series to which we have write access.
filter: Usage :. Filters can combine using a comma ",". Available Filters: managedAcl, contributors, CreationDate, Creator, textFilter, language, license, organizers, subject, title. If API ver > 1.1.0 also: identifier, description, creator, publishers, rightsholder.
sort: Sort the results based upon a list of comma seperated sorting criteria. In the comma seperated list each type of sorting is specified as a pair such as: :ASC or :DESC. Adding the suffix ASC or DESC sets the order as ascending or descending order and is mandatory.
limit(Default value=0): The maximum number of results to return for a single request.
offset(Default value=0): The index of the first result to return.
withacl: Whether the acl should be included in the response.

Status codes: 200: OK, A (potentially empty) list of series is returned.

Testing:

Sample: /?onlyWithWriteAccess={onlyWithWriteAccess}&filter={filter}&sort={sort}&limit=0&offset=0&withacl={withacl}

Testing form (click to reveal)

Form action: /api/series/

onlyWithWriteAccess:		Whether only to get the series to which we have write access.
filter:		Usage :. Filters can combine using a comma ",". Available Filters: managedAcl, contributors, CreationDate, Creator, textFilter, language, license, organizers, subject, title. If API ver > 1.1.0 also: identifier, description, creator, publishers, rightsholder.
sort:		Sort the results based upon a list of comma seperated sorting criteria. In the comma seperated list each type of sorting is specified as a pair such as: :ASC or :DESC. Adding the suffix ASC or DESC sets the order as ascending or descending order and is mandatory.
limit:		The maximum number of results to return for a single request.
offset:		The index of the first result to return.
withacl:		Whether the acl should be included in the response.

Response:

Method / Path: GET /{seriesId}/acl

Description: Returns a series' access policy.

Path params: seriesId: The series id

Optional (query) params: NONE

Status codes: 200: OK, The series' access policy is returned.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/acl

Testing form (click to reveal)

Method / Path: GET /{seriesId}/metadata

Description: Returns a series' metadata of all types or returns a series' metadata collection of the given type when the query string parameter type is specified. For each metadata catalog there is a unique property called the flavor such as dublincore/series so the type in this example would be 'dublincore/series'

Path params: seriesId: The series id

Optional (query) params: type: The type of metadata to return

Status codes: 200: OK, The series' metadata are returned.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/metadata?type={type}

Testing form (click to reveal)

Method / Path: GET /{seriesId}/properties

Description: Returns a series' properties

Path params: seriesId: The series id

Optional (query) params: NONE

Status codes: 200: OK, The series' properties are returned.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/properties

Testing form (click to reveal)

Method / Path: GET /series.json

Description: Returns the series matching the query parameters

Path params: NONE

Optional (query) params: q: Free text search
edit: Whether this query should return only series that are editable
fuzzyMatch: Whether a partial match on series id is allowed, default is false
seriesId: The series identifier
seriesTitle: The series title
creator: The series creator
contributor: The series contributor
publisher: The series publisher
rightsholder: The series rights holder
createdfrom: Filter results by created from (yyyy-MM-dd'T'HH:mm:ss'Z')
createdto: Filter results by created to (yyyy-MM-dd'T'HH:mm:ss'Z')
language: The series language
license: The series license
subject: The series subject
description: The series description
sort: The sort order. May include any of the following: TITLE, SUBJECT, CREATOR, PUBLISHERS, CONTRIBUTORS, DESCRIPTION, CREATED_DATE_TIME, LANGUAGE, RIGHTS_HOLDER, MANAGED_ACL, LICENCE. Add '_DESC' to reverse the sort order (e.g. TITLE_DESC).
offset: The offset
count: Results per page (max 100)

Response formats: application/json

Status codes: 200: OK, The access control list.
401: Unauthorized, If the current user is not authorized to perform this action

Notes:

Return value description: Returns the series search results as JSON

Testing:

Sample: /series.json?q={q}&edit={edit}&fuzzyMatch={fuzzyMatch}&seriesId={seriesId}&seriesTitle={seriesTitle}&creator={creator}&contributor={contributor}&publisher={publisher}&rightsholder={rightsholder}&createdfrom={createdfrom}&createdto={createdto}&language={language}&license={license}&subject={subject}&description={description}&sort={sort}&offset={offset}&count={count}

Testing form (click to reveal)

Form action: /api/series/series.json

q:		Free text search
edit:		Whether this query should return only series that are editable
fuzzyMatch:		Whether a partial match on series id is allowed, default is false
seriesId:		The series identifier
seriesTitle:		The series title
creator:		The series creator
contributor:		The series contributor
publisher:		The series publisher
rightsholder:		The series rights holder
createdfrom:		Filter results by created from (yyyy-MM-dd'T'HH:mm:ss'Z')
createdto:		Filter results by created to (yyyy-MM-dd'T'HH:mm:ss'Z')
language:		The series language
license:		The series license
subject:		The series subject
description:		The series description
sort:		The sort order. May include any of the following: TITLE, SUBJECT, CREATOR, PUBLISHERS, CONTRIBUTORS, DESCRIPTION, CREATED_DATE_TIME, LANGUAGE, RIGHTS_HOLDER, MANAGED_ACL, LICENCE. Add '_DESC' to reverse the sort order (e.g. TITLE_DESC).
offset:		The offset
count:		Results per page (max 100)

Response:

Write methods

Method / Path: POST /

Description: Creates a series.

Path params: NONE

Required (form) params: metadata: Series metadata
acl: A collection of roles with their possible action

Optional (form) params: theme: The theme ID to be applied to the series

Status codes: 201: Created, A new series is created and its identifier is returned in the Location header.
400: Bad Request, The request is invalid or inconsistent..
401: Unauthorized, The user doesn't have the rights to create the series.

Testing:

Sample: /

Testing form (click to reveal)

Method / Path: DELETE /{seriesId}

Description: Deletes a series.

Path params: seriesId: The series id

Optional (query) params: NONE

Status codes: 204: No Content, The series has been deleted.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}

Testing form (click to reveal)

Method / Path: DELETE /{seriesId}/metadata

Description: Deletes a series' metadata catalog of the given type. All fields and values of that catalog will be deleted.

Path params: seriesId: The series id

Required (form) params: type: The type of metadata to delete

Optional (query) params: NONE

Status codes: 204: No Content, The metadata have been deleted.
403: Forbidden, The main metadata catalog dublincore/series cannot be deleted as it has mandatory fields.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/metadata

Testing form (click to reveal)

Method / Path: PUT /{seriesId}

Description: Update all series metadata.

Path params: seriesId: The series id

Required (form) params: metadata: Series metadata as Form param

Optional (form) params: NONE

Status codes: 200: OK, The series' metadata have been updated.
400: Bad Request, The request is invalid or inconsistent.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}

Testing form (click to reveal)

Method / Path: PUT /{seriesId}/acl

Description: Updates a series' access policy.

Path params: seriesId: The series id

Required (form) params: acl: Access policy

Optional (form) params: override: If true the series ACL will take precedence over any existing episode ACL

Status codes: 200: OK, The access control list for the specified series is updated.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/acl

Testing form (click to reveal)

Method / Path: PUT /{seriesId}/metadata

Description: Update a series' metadata of the given type. For a metadata catalog there is the flavor such as 'dublincore/series' and this is the unique type.

Path params: seriesId: The series id

Required (form) params: type: The type of metadata to update
metadata: Series metadata as Form param

Optional (form) params: NONE

Status codes: 200: OK, The series' metadata have been updated.
400: Bad Request, The request is invalid or inconsistent.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/metadata

Testing form (click to reveal)

Method / Path: PUT /{seriesId}/properties

Description: Updates a series' properties

Path params: seriesId: The series id

Required (form) params: properties: Series properties

Optional (form) params: NONE

Status codes: 200: OK, Successfully updated the series' properties.
404: Not Found, The specified series does not exist.

Testing:

Sample: /{seriesId}/properties

Testing form (click to reveal)

External API Series Service REST Documentation

Table of Contents

Read methods

Write methods