Handles CMIP-style (see below) REST requests using a schema definition.
A convention for REST services.
URLs are of the form /<collection>[;<modifiers>][/<identifier>[/<property>]], 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
/<collection>[;<modifiers>][?<filter>]returns a list of objects in the collection. The exact subset returned is determined by the<filter>(see 'collection filters'), and the way each object is represented is determined by<modifiers>(see 'record modifiers'). - GET
/<collection>[;<modifiers>]/<id>returns a single object of the collection identified by id. - POST
/<collection>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
/<collection>/<id>replaces a record with the data given as JSON in the request content. Fields without values provided are reset to their defaults. - PATCH
/<collection>/<id>updates a record with data given as JSON in the request content. Fields not explicitly mentioned retain their old value. - DELETE
/<collection>/<id>deletes a record. - DELETE
/<collection>?<filters>deletes records matching a filter.
Modifiers indicate how to structure the resulting objects.
The with modifier is a comma-separated list indicating what related objects should be returned with each record.
A path like /authors;with=books would indicate to return a list of books with each author record, whereas
a path like /books;with=author,publisher 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 with= lists.
Additional levels of nesting may be requested by using a dot to
separate path components.
e.g. /authors;with=books.publisher.postalAddress 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:
[
{
"id": 154,
"name": "Some Author",
"books": [
{
"id": 301,
"title": "A Book Containing Words",
"publisher": {
"id": 4,
"name": "Some Book Publishing Company",
"postalAddress": {
"streetAddress1": "450 Some Street",
"localityName": "Someville",
"regionCode": "SC",
"postalCode": "12345"
"countryCode": "USA",
}
}
},
...more book records maybe go here...
]
},
...more author records maybe go here...
]
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:
orderBy=[+-]<fieldName>...- indicate sort order of resultslimit=[<skip>,]<count>- indicate how many rows of the result set to skip and include
Field-matching parameter values may be in one of the following formats:
<pattern>- 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.eq:<value>- match a value exactlylike:<pattern>- match a string based on a pattern, where*stands for any substringlt:<value>- matches values less than that givengt:<value>- matches values greater than that givenin:<list>- matches any value that is mentioned in the comma-separated listis:null- matches nullsnot:<expression>- negate a filter, e.g.not:is:nullornot:like:*foo*
Search parameters will be automatically parsed as appropriate given
the field that they are matching on (e.g. if there is a field,
someNumericField that is typed as containing a number, a seach
for someNumericField=eq:5 is interpreted as equals the number 5,
not the string "5")
When translating a database record to its REST form, all primary key
values are combined into a single id, 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.
patient-stays) - field names, both in the URL (modifiers and search parameters) and
in request/response JSON data, are camelCase
(e.g.
patientAdmissionDate)
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 super-duper-car-washes, but the
backing table actually be called x_okaycarwash.
TODO: Add example of using this library in PHP.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent