Ndr interface Dependency Agreement

5.1.4.Person API

Business Operation (per Section 3.3.1)	Permitted Authority	Entity is Identified by	HTTP Method	URL	Input	Success Response	Error Condition Error Response
Create	Any	State State person id	POST	/person//	A Person Entity	The URL for the new Person Entity.	State does not exist Item not found error
Update	Owning Authority	State State person id	POST	/person//	A Person Entity	The URL for the updated Person Entity.	State does not exist Item not found error
Update (Owning Authority) – i.e. when the Person has moved state	The authority of the state to which the Person has moved	State State person id (of the old state)	POST	/person///move (the state and id of the old state)	A Person Owning Authority component (the body of the input includes the new authority and id)	The URL for the updated Person Entity (i.e. in the new state)	State does not exist Item not found error
Update (penalty) – add a new penalty	Any	State State person id	POST	/person///penalty	A Person penalty component	The URL for the updated Person Entity.	State does not exist Item not found error
Update (penalty) – modify an existing penalty	The Authority who applied the Penalty.	State State person id Penalty code Penalty commencement date	POST	/person///penalty	A Person penalty component	The URL for the updated Person Entity.	State does not exist Item not found error
Get (entity)	Any	State State person id	GET	/person//	-	The matching Person Entity.	No matching person Item not found error.
Get (entity)	Any	State State person id	GET	/person///n	-	The matching Person Entity for version number n.	No matching person Item not found error.
Get (entity) – when the Person has moved state	Any	State State person id (of the old state)	GET	/person//	-	The URL for the updated Person Entity (i.e. in the new state)	No matching person Item not found error.
Get (metadata)	Any	State State person id	GET	/person// /meta	-	Metadata for the matching Person Entity.	State / Person Id does not exist Item not found error
Update (entity status)	Owning Authority	State State person id	POST	/person// /entitystatus	Entity status component	The URL for the updated Person Entity.	State / Person Id does not exist Item not found error

5.1.5.Group API

Business Operation (per Section 3.3.1)	Permitted Authority	Entity is Identified by	HTTP Method	URL	Input	Success Response	Error Condition Error Response
Create	Any	State State group id	POST	/group//	A Group Entity	The URL for the new Group Entity.	State does not exist Item not found error
Update	Owning Authority	State State group id	POST	/group//	A Group Entity	The URL for the updated Group Entity.	State does not exist Item not found error
Get (entity)	Any	State State group id	GET	/group//	-	The matching Group Entity.	No matching group Item not found error.
Get (entity)	Any	State State group id	GET	/group///n	-	The matching Group Entity for version number n.	No matching group Item not found error.
Get (metadata)	Any	State State group id	GET	/group///meta	-	Metadata for the matching Group Entity.	State / Group Id does not exist Item not found error
Update (Owning Authority) – i.e. when the Manager of the Group or the Group has moved state	The authority of the state to which the Group Manager has moved.	State State group id (of the old state)	POST	/group///move (the state and id of the old state)	A Group Owning Authority component (the body of the input includes the new authority	The URL for the updated Group Entity (i.e. in the new state)	State does not exist Item not found error
Update (entity status)	Owning Authority	State State person id	POST	/group///entitystatus	Entity status component	The URL for the updated Group Entity.	State / Group Id does not exist Item not found error

5.1.6.Events API

Business Operation (per Section 3.3.1)	Permitted Authority	Entity is Identified by	HTTP Method	URL	Input	Success Response	Error Condition Error Response
Get (events)	Any	-	GET	/events/*	-	Atom feed of events for the specified date.	No events found Atom feed is empty.

* As events are processed in batches it is possible that events processed just after 00:00:00 time can appear in the previous day’s events folder. Events should not be read based on a folder date, rather events should be processed based on the ID of individual event entries. The ID of each event is the system tick time.

5.2.Encryption

Each HTTP request is encrypted via SSL.

5.3.Authentication

Each authority will be issued with a unique key which must be included with each HTTP request.

Two methods are supported for doing this:

#	Method	Details	Example
1	Query String	The key can be appended to the HTTP request as follows: ?authority= Where is either “GET” or “POST” is as shown in the “URL” column of the tables included in Section 5.1 is the unique API key.	GET /dog/abc123?authority=562AFA Host: ndr.galtd.org.au …
2	HTTP Header	The key can also be included in the HTTP header, on a distinct line of the form: “Authority: ” Where is the unique API key.	GET /dog/abc123 Host: ndr.galtd.org.au Authority: 562AFA …

The means of distributing the key is yet to be determined. Each authority is responsible for maintaining the security of the issued key. The key will be changed on request.

5.4.Change Detection

The HTTP Entity Tag (ETag) is used to identify a particular version of an Entity within the NDR and is designed to prevent the overwriting of entities.

In addition, a version of the entity can be accessed using the GET method using an integer to represent the version. For example, the following URI for a GET operation will return version 1 of the Person 300037 entity:

http://machineURI/person/NSW/300037/1

As can be seen below, the response header contains both an ETag value and entity version 1:

HTTP/1.1 200 OK
Cache-Control: private, no-store
Content-Type: text/xml; charset=utf-8
Expires: Wed, 31 Dec 1969 13:00:00 GMT
ETag: "0x8CF5F5F26695B60"
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 3.0
EntityVersion: 1
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Thu, 13 Sep 2012 00:41:51 GMT
Content-Length: 1306

...

The standard usage of ETags in relation to GET and POST methods is as follows:

Method	Request	If the NDR holds a later version of the Entity than the client making the request …	If NDR does not hold a later version of the Entity than the client making the request …
GET	Header includes a line of the form: “If-None-Matches: ” where corresponds to the version of the Entity held by the client.	NDR returns the requested Entity. The header of the response includes a line of the form: “ETag: ” where corresponds to the requested Entity.	NDR returns a response with Status Code “304 Not Modified”. The body of the response is empty.
POST	Header includes a line of the form: “If-Match: ” where corresponds to the version of the Entity held by the client.	NDR does not accept the update. NDR returns an error response with Status Code “412 Precondition Failed”.	NDR accepts the update. The header of the response includes a line of the form: “ETag: ” where corresponds to the updated Entity.

Further detail, including more details of the request and the response, is laid out in Section 10.