item-and-collection hypermedia-schemas

Providing generic item & collection hypermedia-schemas

1. item-schema with links like: [self,item,update,delete]
2. collection-schema with links like: [self,add,"paginate"], $ref: [item-schema]

Idea + solution from here (lb3) :
https://www.npmjs.com/package/loopback-jsonschema#item-and-collection-schemas

Metadata might be served from /schemas/ or /item-schemas/ -endpoint - and allow CRUD

Use Cases

1. reference item/collection-schema in custom mime-type
2. unify access to docs and validation schemas
3. have generic API-Browser

Item Schema example

curl -i http://example.org/api/item-schemas/people

{
  "id": "537530ea27f8870b63f2d886",
  "type": "object",
  "title": "Person",
  "collectionTitle": "People",
  "collectionName": "people",
  "links": [
    {
      "rel": "self",
      "href": "http://example.org/api/people/{id}"
    },
    {
      "rel": "item",
      "href": "http://example.org/api/people/{id}"
    },
    {
      "rel": "update",
      "method": "PUT",
      "href": "http://example.org/api/people/{id}"
    },
    {
      "rel": "delete",
      "method": "DELETE",
      "href": "http://example.org/api/people/{id}"
    }
  ],
  "$schema": "http://json-schema.org/draft-04/hyper-schema#"
}

collection Schema example

curl -i http://example.org/api/collection-schemas/people

{
  "$schema": "http://json-schema.org/draft-04/hyper-schema#",
  "title": "People",
  "type": "array",
  "items": {
    "$ref": "http://example.org/api/item-schemas/people"
  },
  "links": [
    {
      "rel": "self",
      "href": "http://example.org/api/people"
    },
    {
      "rel": "add",
      "method": "POST",
      "href": "http://example.org/api/people",
      "schema": {
        "$ref": "http://example.org/api/item-schemas/people"
      }
    },
    {
      "rel": "previous",
      "href": "http://example.org/api/people?filter[limit]={limit}&filter[offset]={previousOffset}{&paginateQs*}"
    },
    {
      "rel": "next",
      "href": "http://example.org/api/people?filter[limit]={limit}&filter[offset]={nextOffset}{&paginateQs*}"
    },
    {
      "rel": "page",
      "href": "http://example.org/api/people?filter[limit]={limit}&filter[offset]={offset}{&paginateQs*}"
    },
    {
      "rel": "order",
      "href": "http://example.org/api/people?filter[order]={orderAttribute} {orderDirection}{&orderQs*}"
    }
  ]
}