Skip to content

Latest commit

 

History

History
83 lines (53 loc) · 2.83 KB

README.md

File metadata and controls

83 lines (53 loc) · 2.83 KB
Raw

REST Object Tree Generator

1. Usage

1.1. Generate

Prepare the new openapi.yaml specification and generate the REST API server source code.

npm run generate

You can easily define objects and tree branches in config/config.yaml.

Choose one of the predefined generators or create a new one in src/generator/*.js.

This project uses .mustache files as templates.

1.2. Serve

Launch the REST API and its OpenAPI v3 documentation:

npm run serve

2. Components

2.1. Objects

📚 Template {becomes} Draft {published on-chain to} Object.

You cannot create objects or object drafts directly.

  1. PUT /object/x/template/{templateId}/{objectId}/ to create a Draft inside Object (added if missing)

You cannot update objects or object versions directly.

  1. PUT /object/x/{objectId}/draft/{draftId}/ to publish Draft to Object (append to version chain)
  2. PUT /object/x/{objectId}/version/{version}/ to revert Object to version (trim version chain)

Drafts are discarded after publishing.
Schemas can only be created and modified in Templates.

Template Draft Object
Data Editable Editable Read-only (versionized)
Schema Editable Read-only Read-only (versionized)

Data migration is the same as user input so it must be handled at the application level, not at the API level:

  1. POST | GET /object/x/template/{templateId}/ - (once) Prepare new schema and default data
  2. GET /object/x/{objectId}/ - Fetch current object data, schema and schema ID
  3. Inside application - migrate data using #1 and #2
  4. PUT /object/x/template/{templateId}/{objectId}/ with publish=true - Update Object with new data & schema

Applications should display any schema.
Data migration should be performed on user request.

2.2. Trees

Trees define relationships between Objects.

Configure the branch structure using cardinality. Use exclamation mark (!) for 1:

  1. many-to-many Example: /tree/team/user
  2. one-to-many Example: /tree/organization!/team
  3. many-to-one Example: /tree/user/!level
  4. one-to-one Example: /tree/user!/!logo

Note: the exclamation mark syntax is only used inside the config.yaml file to define cardinality! Final REST API endpoints use only the pre-defined object names, i.e. /tree/user/logo instead of /tree/user!/!logo.

3. Sample output

This OpenAPI v3 specification is generated by default when first executing npm run generate.