Quickstart eliobones

• eliobones Prerequisites
• Installing eliobones

Nutshell

Restful eliobones API implement a common standard.

Anatomy of an eliobones API

Auth

• loginT POST /auth/:T Exchange a username and password for a Permit. Unprotected.
• logoutT DELETE /auth/:T/:id Expire the Permit.

Engage

• takeupT POST /engage/:T "Takeup" a Thing of schemaType :T, e.g. "Thing", "MedicalCondition", "Vehicle". Unprotected.
• updateT PATCH /engage/:T/:id Update an engaged Thing.
• readT GET /engage/:T/:id View the engaged Thing.
• destroyT DELETE /engage/:T/:id Delete an engaged Thing (doesn't destroy any Things in its list).

List

• takeonT POST /list/:T/:id/:LT "Takeup" then "TakeOn" a new Thing of schemaType :LT and add it to the engaged Thing's list.
• listT GET /list/:T/:id View the engaged Thing's list.
• enlistT PUT /list/:T/:id/:LT/:lid En list an existing Thing.
• unlistT DELETE /list/:T/:id/:LT/:lid Un list an existing Thing.

Schema

• schemaT GET /schema/:T Get the Meta Schema of schemaType :T. Unprotected.
• schemaT GET /schema/:t Get an empty instance of schemaType :t. Unprotected.

The idea. A bit like how nedb works, but without the merge.

• TODO: A Database starts with a FROZEN initial state.
• TODO: All the above actions get stored as changes.
• TODO: Existing "intime" changes are played by default on the app start.
• TODO: New Actions are added to the "intime" database of changes.
• TODO: Actions are BLOCKCHAIN transactions?

Bones APIs

All eliobones APIs should, by design, enforce the priciple's of elioWay.

• A cult, not a framework

All eliobones APIs should provide endpoints for data modelled on every https://schema.org documented schemaTypes.

Largely speaking eliobones APIs handle standard requests like PATCH, DELETE, GET as you would expect, except with a couple of notable exceptions which are detailed below.

SchemaType is a parameter

Where http://bones.api/ is your domain, there should always be a parameter for schemaType, e.g

• GET http://bones.api/:engage/:id/

We will call this the engage parameter, representing the schemaType being engaged (duh!).

schema Endpoint

There should always be an endpoint which can respond with the meta information of a given schemaType. The client can use this meta data to auto-generate the MVC classes, or simply to render a form with inputs tailored to the fields of the schemaType.

• http://bones.api/schema/:engage/

Takes 1 parameter:

• engage: The schemaType you want to retrieve.

Examples:

• http://bones.api/schema/Thing/
• http://bones.api/schema/Hospital/
• http://bones.api/schema/CreativeWork/
• http://bones.api/schema/MedicalImagingTechnique/
• http://bones.api/schema/FoodEstablishmentReservation/

signup Endpoint

In eliobones there is no separate Auth model. We take the view that because one Thing isn't so unlike another, the Auth Model will just be one of the many schemaTypes.

• POST http://bones.api/signup/:engage/

• Posting to http://bones.api/signup/Thing/ will create a new Thing, as long as you provide username and password. Signin to engage it.

• Posting to http://bones.api/auth/signup/Hospital/ will create a new Hospital, as long as you provide username and password. Signin to engage it.

• Whether you Signin to engage a Thing or Hospital makes no difference, and you can start to list, engage and iterate on either. However, if you enter the "account settings" of the signed in Hospital, you will be able to edit the Thing fields, the Extra fields for Hospital including Place fields (which Hospital subclasses).

• In the App of Apps, the signedin Thing is the App.

login and logout Endpoints

These endpoints do not need parameters. Simply post the username and password (or credentials) to login, and send nothing except an active session to logout.

• POST http://bones.api/login/
• GET http://bones.api/logout/

get Endpoint

Returns a single Thing with all its fields.

• GET http://bones.api/:engage/:id/

Takes 2 parameters:

• engage: The schemaType you want to engage. Even though it isn't required, we suggest including this as it has semantic value.
• id of the Thing you want to engage

list Endpoint

Returns a slim list of Things belonging to the list property of the engaged Thing.

• GET http://bones.api/:engage/:id/list

Takes the same parameters as get

Comparing get with get list:

• http://bones.api/Hospital/Abc123/ responds with the engaged Hospitals fields including the list field as an Array of MongooseObjectIDs.
• http://bones.api/Hospital/Abc123/list/ responds with the engaged Hospitals list field as an Array of slim JSON objects, with core fields such as id, name, description, image, etc - which you can render as ul or table.

list with Filter Endpoint

Returns a slim list of Things belonging to the list property of the engaged Thing which are filtered to just one schemaType.

• GET http://bones.api/:engage/:id/list/:T

Takes the same parameters as get +

• T: Filter the list to this given schemaType.

Examples:

• http://bones.api/FoodEstablishment/Abc123/list/MenuItems
• http://bones.api/FoodEstablishment/Abc123/list/FoodEstablishmentReservation

create Endpoint

In eliobones you can't POST to CREATE a new Thing to a parameterless URL. New Things are always created for an engaged Thing, and added to its list.

Starting from scratch, you should use the signup endpoint described above.

• Posting to http://bones.api/Thing/ WON'T create a new Thing.

• Posting to http://bones.api/Hospital/Abc123/MedicalImagingTechnique WILL create a new MedicalImagingTechnique and add it to Hospital Abc123's list.

• POST http://bones.api/:engage/:id/:T

Takes the same parameters as get +

• T: The schemaType of the Thing being added to the engaged Thing's list.

Examples:

• http://bones.api/FoodEstablishment/Abc123/FoodEstablishmentReservation
• http://bones.api/FoodEstablishment/Abc123/MenuSection
• http://bones.api/MenuSection/Def456/MenuItem

update and delete Endpoints

These work as you'd expect:

• PATCH http://bones.api/:engage/:id/
• DELETE http://bones.api/:engage/:id/

Both take the same parameters as get.

Creating a new eliobones app

1. Use yo thing to create a new app elioway/eliobones/bones-inFramework.
2. Build a Restful API in the framework of your choice.
3. If required: Create a new Schema Builder in your/repo/elioway/eliothing/thing-inFramework folder.
4. Get it working.
5. Test it.
6. Document it using chisel.
7. Brand it using generator-art. Tell everyone about it.
8. Use it to do things the elioWay.
9. Push it to the https://gitlab.com/eliobones/.