loopbackio / loopbackio/loopback-next

item-and-collection hypermedia-schemas

Open
#5,619 1 comment 0 reactions 1 assignee View on GitHub

@achrinza is already working on this.

Since Sep 20, 2020.

Extensions feature
Dominant language
TypeScript
Stars
5.1k
Forks
1.1k
Avg merge
2d 21h
Merged PRs (30d)
27

Description

## 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`

```js
{
"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`

```js
{
"$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*}"
}
]
}
```

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.