Download the PHP package earthit/cmip-rest without Composer

CMIP REST

Handles CMIP-style (see below) REST requests using a schema definition.

What the heck is CMIP

A convention for REST services.

URLs are of the form , hence 'CMIP'.

It also supports some other styles, mapping them to the same underlying operations.

There are five basic operations: search, get, post, put, patch, delete.

• GET returns a list of objects in the collection. The exact subset returned is determined by the (see 'collection filters'), and the way each object is represented is determined by (see 'record modifiers').
• GET returns a single object of the collection identified by id.
• POST add new records to the collection. The new records are provided as a JSON-encoded list in the request. If items POSTed include primary keys, they may conflict with existing items, in which case those items are updated as if a PATCH was done on those items.
• PUT replaces a record with the data given as JSON in the request content. Fields without values provided are reset to their defaults.
• PATCH updates a record with data given as JSON in the request content. Fields not explicitly mentioned retain their old value.
• DELETE deletes a record.
• DELETE deletes records matching a filter.

Record modifiers

Modifiers indicate how to structure the resulting objects. The modifier is a comma-separated list indicating what related objects should be returned with each record. A path like would indicate to return a list of books with each author record, whereas a path like would indicate to return a single author and publisher with each book record. The set of related objects that may be requested is defined by the service, and services may provide alternate modifiers, possibly as aliases for long lists.

Additional levels of nesting may be requested by using a dot to separate path components. e.g. to get a list of authors, each of which contains a list of all their books, each of which contains a 'publisher' record with a 'postalAddress' sub-record. The resulting JSON might look something like:

Collection filters

Except for a few reserved parameters, query parameters to a collection GET request correspond to fields of the items in the collection.

The reserved parameters are:

• • indicate sort order of results
• • indicate how many rows of the result set to skip and include

Field-matching parameter values may be in one of the following formats:

• • match a pattern where stands for any substring. Only valid if the pattern does not contain a colon. May be optimized as an exact match if the given pattern doesn't contain any asterisks.
• • match a value exactly
• • match a string based on a pattern, where stands for any substring
• • matches values less than that given
• • matches values greater than that given
• • matches any value that is mentioned in the comma-separated list
• • matches nulls
• • negate a filter, e.g. or

Search parameters will be automatically parsed as appropriate given the field that they are matching on (e.g. if there is a field, that is typed as containing a number, a seach for is interpreted as equals the number 5, not the string "5")

Collection-Table mapping

When translating a database record to its REST form, all primary key values are combined into a single , with multiple fields separated by dashes.

When interpreting an ID given in a URL or in JSON, it must be converted to its component fields. Even if there really is only a single ID field int the database record, the ID data from JSON or the URL must be converted to the correct type.

Field names may be translated between naming conventions when loading and storing. The naming convention for tables and columns in Postgres seems to be to use squishedtogetherlowercase.

In the view exposed by the REST services:

• collection name is dash-separated (e.g. )
• field names, both in the URL (modifiers and search parameters) and in request/response JSON data, are camelCase (e.g. )

It is a goal of this project to make it simple to override these conventions and to allow special cases for different views of things. e.g. a class may be exposed as , but the backing table actually be called .

TODO: Add example of using this library in PHP.