Feed API 4.0

Status

Version: draft, last update: 10-02-2012

Resources

The feed API 4.0 contains 4 basic resources and 1 "recipe" resource. The figure below shows the several relations between resources.

Resource	Description	Operation	XML schema
search	Represents the search resource which is an entry point for several resources	GET	event.xsd
group	Represents the group resource, this resource contains one or more events	GET, POST, PUT & DELETE	group.xsd
event	Represents the event resource, this resource belongs to a group and contains a production and a location.	GET, POST, PUT & DELETE	event.xsd
production	Represents the production resource, this resource belongs to an event.	GET, POST, PUT & DELETE	production.xsd
location	Represents the location resource, this resources belongs to an event.	GET, POST, PUT & DELETE	location.xsd
nubxml	Represents the current NUBXML (API 3.0)	GET	nubxml.zip

URI templates

The table below gives a description of the URI templates which can be used for retrieving resources.

URI	Desctiption
/search	Displays a list with links to resources
/groups	Displays a list of groups
/groups/{id}	Displays a group with a certain {id}
/groups/{id}/events	Displays a list of events for a group with a certain {id}
/groups/{id}/productions	Displays a list of productions for a group with a certain {id}
/groups/{id}/locations	Displays a list of locations for a group with a certain {id}
/events	Displays list of events
/events/{id}	Displays an event with a certain {id}
/events/{id}/groups	Displays list of groups for an event with a certain {id}
/events/{id}/productions	Displays list of productions for an event with a certain {id}
/events/{id}/locations	Displays list of locations for an event with a certain {id}
/events/statuses	Displays list of event statuses
/events/types	Displays list of event types
/productions	Displays list of produtions
/productions/{id}	Displays a productions with a certain {id}.
/productions/{id}/groups	Displays list of groups for a production with a certain {id}
/productions/{id}/events	Displays list of events for a production with a certain {id}
/productions/{id}/locations	Displays list of locations for a production with a certain {id}
/productions/genres	Displays list of production genres
/productions/types	Displays list of production types
/locations	Displays list of locations
/locations/{cidn}	Displays an location with a certain {cidn}
/locations/{cidn}/groups	Displays list of groups for location with a certain {cidn}
/locations/{cidn}/events	Displays list of events for location with a certain {cidn}
/locations/{cidn}/productions	Displays list of productions for location with a certain {cidn}
/locations/types	Displays list of location types
/nubxml	Displays list of events in the NUBXML format

Links between resources

The NUB API supports hypermedia: distributed hypermedia provides a uniform means of accessing services through the embedding of action controls within the presentation of information retrieved from remote sites. In the NUB API hypermedia is represented as a <link> tag within resources. Below an example of a link:

<link ref="http://resources.uitburo.nl/productions/74574574575754754747" type="production" cidn="74574574575754754747"/>

Where type is one of groups, event, location of production. Hypermedia can be resolved server side by providing a resolve=true filter while requesting the resource. The group resource contains a link to one or more event(s). The event resource contains links to a production and location resource.

Search resources

The Publishing Server 4.0 has a search entry point, which means a central place to ask questions to the platform. The search result is a list with links to several resources on the platform. All resource filters can be used with the search entry. Below an example of searching resources with locale en_UK.

GET /search?locale=en_UK HTTP/1.1

This will result in:

<search>
   <hits>5</hits>
   <rows>10</rows>
   <start>0</start>
   <link cidn="2042272fda0e4803954a6d16313bac74" resource="group" ref="http://feeds.uitburo.nl/api/groups/2042272fda0e4803954a6d16313bac74"/>
   .
   .
   .
   <link cidn="2042272fda0e4803954a6d16313bac74" resource="nubxml" ref="http://feeds.uitburo.nl/api/nubxml/2042272fda0e4803954a6d16313bac74"/>
</search>

With the parameter resolve=true it is possible to resolve the <link> element server side.

Filter resources

General filters

key	xs:string	All requests must include the access key for your account. This key will be used to retrieve your account and apply any account specific filtering during searches.
rows	xs:int	Defines the number of results to return in the current request. This can be considered as the page size, and for most users it makes sense to use the same number for each request. For example ?rows=20 returns a resultset with 20 resources.
start	xs:int	Defines the starting index for the current page of search results. A search can potentially result in thousands of results.
locale	xs:string	Defines the language to search in, possible values are: nl_NL, fr_NL, en_UK, en_EN & de_DE
resource	xs:string	Search on resource, possible values are: groups, events, locations, productions.
createdfrom	xs:dateTime	Display resources created from a certain date.
createdto	xs:dateTime	Display resources created to a certain date
modifiedfrom	xs:dateTime	Display resources modified from a certain date
modifiedto	xs:dateTime	Display resources modified to a certain date

Group filters

filter

xs:int

description

Event filters

filter

xs:int

description

Production filters

filter

xs:int

description

Location filters

filter

xs:int

description

NUBXML filters

filter

xs:int

description

Changes

29-12-2011	Initial version
27-01-2012	Uploaded new versions of the sample files and xml schema's
10-02-2012	Added new versions of the XML schema's