Ndr interface Dependency Agreement

5.5.2.Components

	Business Operation (refer Section 5.1)	Component
Dog – Earbrand	Update (earbrand)	dog_earbrand.xsd
Dog – Name	Update (name)	dog_name.xsd
Dog – Dna	Update (dna)	dog_dna.xsd
Dog – Studsire	Update (studsire)	dog_studsire.xsd
Dog – Lifestate	Update (lifestate)	dog_lifestate.xsd
Dog – Microchip	Update (microchip)	dog_microchip.xsd
Dog – Certificate	Update (certificate)	dog_certificate.xsd
Dog – Owner	Update (owner)	owner.xsd
Dog – Trainer	Update (trainer)	trainer.xsd
Dog – Penalty	Update (penalty)	dog_penalty.xsd
Dog – Trial	Update (trial)	dog_trial.xsd
Dog – Authority to breed	Update (authority to breed)	dog_authority_to_breed.xsd
Dog –Entity status	Update(dog entity status)	dog_update_entity_status.xsd
Litter – Whelping	Update (whelping)	litter_whelping.xsd
Litter – Entity status	Update(litter entity status)	litter_update_entity_status.xsd
Person – Owning Authority	Update (Owning Authority)	person_owningauthority.xsd
Person – Penalty	Update (penalty)	person_penalty.xsd
Person – Entity status	Update(person entity status)	person_update_entity_status.xsd
Group – Entity status	Update(group entity status)	group_update_entity_status.xsd
Meeting – Entity status	Update(meeting entity status)	meeting_update_entity_status.xsd

5.5.3.Events

The following schemas define the XML component that is returned from one of the Get (Events) operations. In each case, the returned component is an Atom feed (defined by atom.xsd), extended in accordance with an element of type Event Details Type (defined within the schema types.xsd).

Entity	Business Operation (ref Section 5.1)	Schema
All	Get (events)	atom.xsd

Note that the NDR will only populate a small subset of the attributes defined in the Atom feed. The list of attributes to be populated is as follows:

Element	Defined in Schema	Attribute	Meaning
feed	atom.xsd	updated	The time stamp on the Feed.
		title	The title of the Feed, e.g. “NDR Events”.
		subtitle	The subtitle of the Feed, e.g. “Ndr Events for 2012-01-30”
		id	The unique identifier of the feed.
		link	The link to the Events file.
entry	types.xsd (within eventDetailsType)	owning authority	The Owning Authority of the Entity after the event has occurred.
		previous authority	The Owning Authority of the Entity before the event has occurred (this will only differ from the “owning authority” if the Owning Authority has changed).
		transaction authority	The authority that made the request that gave rise to the event.
		name	The human readable name of the Entity on which the event occurred; e.g. the full name of a Person.
		eventType	The type of event.
		description	A free text description of the event.
	atom.xsd

5.5.4.Metadata

Metadata refers to the data associated with each record in the NDR, such as ownership, relative links, current version index and versions. This data can be read, but cannot be written, by clients.

The current version of the entity is stored in the element.

The following schema defines the XML component that is returned from one of the Get (metadata) operations.

Entity	Business Operation (ref Section 5.1)	Schema
All	Get (metadata)	meta.xsd

Note that the information contained within an Events file and the Metadata is essentially the same. It is just that the Events file contains all updates for a given date, whereas Metadata contains all updates for a given Entity.

5.5.5.Type Definitions

The following schema defines types used in the previously listed schemas.

	Schema
Types	types.xsd

5.6.Validation

The following validation is performed on each request:

Request	Validation	Test Performed
Any	Authentication	Has the user provided a valid API key, in accordance with Section 5.2?
Any	Integrity of URL	Is the URL correctly formed?
POST	Structural Integrity	Does the body of the request conform to the relevant XSD?
POST	Write Permissions	Is the authority permitted to make the request, as defined in Section 4.2.2?
POST	Update is not based on stale data	Does the ETag included in the POST request correspond to the latest version of the Entity that is being updated?

5.7.Status Codes

The response to each HTTP request will include a standard HTTP Status Code, as per the following tables:

5.7.1.Valid Requests

Request	Success Scenario	HTTP Status Code
GET	The data corresponding to an Entity is read from the NDR.	200 OK
POST	A new Entity is created in the NDR.	201 Created
GET	There is no update since the previous GET.	304 Not Modified
GET	The requested resource does not exist. (Note: This is still considered a valid request.)	404 Not Found
GET (Dog)	The Dog earbrand has changed. (Note: This is still considered a valid request.)	301 Moved Permanently
GET (Person)	The Person has moved state. (Note: This is still considered a valid request.)	301 Moved Permanently

5.7.2.Invalid Requests

The following error scenarios correspond to failure of the validation outlined in Section 5.6.

Request	Validation	Error Scenario	HTTP Status Code
Any	Authentication	Invalid credentials.	401 Unauthorized
Any	Integrity of URL	The URL is malformed.	404 Not Found
POST	Structural Integrity	The body of the request is malformed (i.e. it does not conform to the XSD).	400 Bad Request
POST	Write Permissions	The request attempts to modify read-only data.	401 Unauthorized
POST	Update is not based on stale data	The ETag included in the POST request does not correspond to the version of the Entity held by the NDR.	412 Precondition Failed

6.End to End Scenarios

This section describes some key end to end scenarios which make use of the NDR interface.

6.1.Success Scenarios

6.1.1.End to End Process for Assigning / Updating a Dog Name

The following diagram and table defines the sequence of events involved in assigning or updating the name of a greyhound.

Figure – Sequence of Events in Naming a Greyhound. The steps highlighted in blue impact the NDR.

Step	Description	Call to NDR	Comment
1	An individual lodges a naming application through their State Body.	(none)	This process by which this occurs may vary from state to state.
2	The State Body validates the request.	(none)	This process by which this occurs may vary from state to state.
3	The State Body lodges the naming application with GA via the Naming Application interface.	(none)	The Naming Application interface is supported by the GA Web Portal, rather than by the NDR. It is not defined in the current document.
4	GA applies business rules to determine which, if any of the requested names are assigned to the greyhound.	(none)	GA may, at its discretion, assign a name other than one of the requested names.
5	If a name is assigned, the new name is pushed from GA into the NDR.	Dog – Update (Name)
6	The State Body receives updates from the NDR.	Get (Events)