CIDN Register API

Introduction

The CIDN Register provides a simple REST API for adding and searching for register objects (productions, locations and people). Adding objects requires posting XML definitions of the objects, and all requests result in an XML response. The following page describes each of the supported requests, including the XML formats and supported parameters.

This document is updated on 1st november 2011.

What is a CIDN?

In the CIDN Register, each object is given a unique identifier called a CIDN (Cultural IDentification Number). To prevent any semantic meaning being embedded in the CIDN, the Register uses 128-bit UUIDs. An example of a CIDN is "60736d6c-b58c-470a-8ccc-5e32758f99de". For more information about the CIDN/UUID generator, see Java's documentation

Resources registered on the CIDN

The CIDN Register support 3 kinds of resources: productions, locations and partys. For every resource the attributes below are registerd.

General

cidn	xs:string	Unique CIDN of the object. When new objects are added to the register, they are assigned their CIDN, therefore it is not necessary to include this value in add object requests.
date-added	xs:dateTime	Date that the object was first added to the register. When new objects are added to the register, this value is set by the register itself.
author	xs:string	Name of the person/organisation that added the object to the register. It is left up to the source of the add object request, to determine what they wish to be known as.
status	xs:string	Status (active, deleted, duplicatie or marked) information of a resource and is set by the register itself.

Productions

<production>
   <cidn/>
   <date-added/>
   <author/>
   <status/>
   <title/>
   <genre/>
   <season/>
   <party/>
</production>

title	xs:string	Title of the Production.
genre	xs:string	A key for the genre, which can be found on http://cidn.uitburo.nl/productions/genres.
season	xs:string	A key for the season, which can be found on http://cidn.uitburo.nl/productions/seasons
party	xs:string	CIDN of a party, which can be found on http://cidn.uitburo.nl/partys

Locations

<location>
   <cidn/>
   <date-added/>
   <author/>
   <status/>
   <name/>
   <postalcode/>
   <streetnumber/>
   <geohash/>
</location>

name	xs:string	Name of the location
postalcode	xs:string	A postalcode for a location
streetnumber	xs:string	A streetnumer for the location
geohash	xs:string	A geohash, which can be derived from http://geohash.org/

Partys

<party>
   <cidn/>
   <date-added/>
   <author/>
   <status/>
   <name/>
   <type/>
   <dayofbirth/>
   <term/>
</party>

name	xs:string	Name of the party
type	xs:string	The type of party, which can be found on http://cidn.uitburo.nl/partys/types
dayofbirth	xs:dateTime	Day of birth of party
term	xs:string	A free text term of a party

Retrieving resources

Retrieve a list of resources

The request below shows a HTTP request for retrieving productions.

GET /productions HTTP/1.1

This will result in the following result:

<productions>
  <hits>1</hits>
  <rows>10</rows>
  <start>0</start>
  <production>
    <cidn>3a21c1cb-dec5-4de1-9c2d-61cec978a01d</cidn>
    <date-added>2011-09-01T12:31:00.000</date-added>
    <author>Uitburo</author>
    <name>Superbaby in de dierentuin</name>
    <genre>jeugd</genre>
    <season/>
    <party/>
 </production>
</productions>

The request below shows a HTTP request for retrieving locations

GET /locations HTTP/1.1

The request below shows a HTTP request for retrieving partys

GET /partys HTTP/1.1

Filter resources

The following filters can be applied to filter resources

text (1	productions, locations, partys	xs:string	Full text search on all resources.
title	productions	xs:string	Title of the production.
genre	productions	xs:string	A key for the genre, which can be found on GET /productions/genres HTTP/1.1.
season	productions	xs:string	A key for the season, which can be found on GET /productions/seasons HTTP/1.1
party	productions	xs:string	CIDN of a party, which can be found on GET /partys HTTP/1.1
name	locations	xs:string	Name of the location
postalcode	locations	xs:string	A postalcode for a location
streetnumber	locations	xs:string	A streetnumber for a location

(1 The text search meets the Lucene Query Parser Syntax

Below an example of a HTTP request for retrieving productions with genre jeugd

GET /productions?genre=jeugd HTTP/1.1

Retrieve a specific resource

The request below shows a HTTP request for retrieving a specific production with given CIDN.

GET /productions/3a21c1cb-dec5-4de1-9c2d-61cec978a01d HTTP/1.1

This will result for example following XML response

<production>
   <cidn>3a21c1cb-dec5-4de1-9c2d-61cec978a01d</cidn>
   <date-added>2011-09-01T12:31:00.000</date-added>
   <author>Uitburo</author>
   <name>Superbaby in de dierentuin</name>
   <genre>jeugd</genre>
</production>

HTTP status codes

The CIDN register returns the following HTTP status codes.

HTTP 200	OK	Request returned result
HTTP 301	MOVED PERMANENTLY	The requested resource has a parent resource and therefore the request is redirected to the parent resource
HTTP 500	ERROR	An error has occurred.

Registering a specific resource

It is possible to register a specific resource on the CIDN register. Use the HTTP POST request and provide the XML of a production, location or party as the content body. The request needs the application/xml content type. Below an example of registering a production on the CIDN register.

POST http://cidn.uitburo.nl/productions?key={apikey}

With body content:

<production>
   <author>Uitburo</author>
   <title>Superbaby in de dierentuin</title>
   <genre>jeugd</genre>
</production>

Duplicate check

When registering a production, location or party the CIDN register executes a duplicate check. The check is based on several attributes of a resource. When the check exceeds a certain threshold level, the CIDN register will return a HTTP 406 (NOT ACCEPTED) status code and a list of resources which are candidate duplicates. The table below shows the duplicate check algorithm for the fields of the different resources.

production	title	fuzzy match	location	name	fuzzy match	party	name	fuzzy match
production	season	exact match	location	postalcode	exact match	party	type	exact match
production	genre	exact match	location	streetnumber	exact match	party	dayofbirth	exact match
production	party	exact match	location	geohash	exact match

HTTP status codes

The CIDN register will return the following HTTP status codes:

HTTP 201	CREATED	Request returned result
HTTP 406	NOT ACCEPTED	The request is not allowed, because a duplicate resource exists in the CIDN register
HTTP 500	ERROR	An error has occurred.