Skip to content

Working with Resources

Andrew Cooke edited this page Aug 27, 2021 · 6 revisions

About Resources

Resources are the main objects that you can GET (and where supported, POST, PUT, or PATCH) using ICAR ADE APIs. Resource schemas form a heirarchy inherited from the base icarResource, using the JSON Schema allOf keyword.

You will find resources in the /resources folder within the JSON code.

Resource inheritance

icarResource

This schema defines the self-link @id which is used to find the URL of a resource. This is useful when you retrieve an collection of resources, and then need to know the URL to a single resource instance. The schema also embeds a meta data type (meta, of type icarMetaDataType). This defines attributes such as the date the resource was last modified. You will find all the resources that are intended to be accessed via a URI in the /resources/ folder.

icarResourceReference

This type defines a reference to a resource, including both its ID and a URI link to the resource itself.

icarEventCoreResource

This schema is a base class for all animal events. It defines a unique id for each event, the event date and time (eventDateTime), and provides the identity of the animal and the location at which the event was recorded. Specific schemas for each event type all include icarEventResource using the JSON Schema allOf keyword.

A note regarding eventDateTime: When specifying dates in icarEventResource and other ICAR entities, date times MUST specify time zone, and SHOULD generally use UTC (using the special "Z" designator as per IS8601 and W3C guidelines).

Collections of Resources - icarResourceCollection

Most of the example URL schemes in this repository return a collection of resources. These collections derive from icarResourceCollection, modifying the member array item to be the specific type of resource returned. The collection is decorated with additional fields that (optionally) support pagination, including first, last, next, and previous URI references.

icarResourceCollectionReference

This resource type represents a reference to a collection. It tells you the type of the resources in the collection, the number of items and default page size, as well as supported operations, in a way that is discoverable and will be familiar to both JSON-LD and JSON-API developers (without being bound into either syntax).

Clone this wiki locally