Jangle API

A RESTful API built on top of Jangle Core.

Overview

Jangle Core did all the hard work: Storing content, publishing, history, authentication. Jangle API is the layer on top that allows us to access our Jangle CMS content via automatically generated API endpoints.

This API is broken up into these major components:

Authentication API
List API
Item API

Authentication API

Creating users, signing in, getting tokens.

Can Sign Up

GET /api/auth/can-sign-up

Find out if sign-up is allowed. Useful for sign-up / sign-in screens.

Example

GET /api/auth/can-sign-up

Returns

If sign up is allowed:

{
	"error": false,
	"message": "Sign up allowed!",
	"data": true
}

If another user already exists:

{
	"error": false,
	"message": "Cannot sign up.",
	"data": false
}

Sign Up

POST /api/auth/sign-up

Create a new user for our Jangle instance, if no other users exist in the system.

Body

name - The display name for the new user.
email - The email for the new user.
password - The password for the new user.

Example:

{
	"name": "Ryan",
	"email": "ryan.nhg@gmail.com",
	"password": "jangleIsEasy"
}

Returns

If everything went okay, and the user was signed up:

{
	"error": false,
	"message": "Sign up successful!",
	"data": {
		"name": "Ryan",
		"email": "ryan.nhg@gmail.com",
		"token": "<ryans-token>"
	}
}

If a user already exists (/api/auth/can-sign-up returned false):

{
	"error": true,
	"message": "Admin user already exists.",
	"data": null
}

If the user provided was invalid:

{
	"error": true,
	"message": "Could not create admin user.",
	"data": null
}

Sign In

GET /api/auth/sign-in

Body

email - The email for the user.
password - The password for the user.

Example:

{
	"email": "ryan.nhg@gmail.com",
	"password": "jangleIsEasy"
}

Returns

If the sign in was successful:

{
	"error": false,
	"message": "Sign in successful!",
	"data": {
		"name": "Ryan",
		"email": "ryan.nhg@gmail.com",
		"token": "<ryans-token>"
	}
}

If that user doesn't exist or the password doesn't match:

{
	"error": true,
	"message": "Failed to sign in.",
	"data": null
}

List API

Viewing and updating items in Jangle Lists.

Overview

The List API exposes Jangle Core's function using RESTful API standards. Once you are familar with the List API, the Items API will feel super easy!

Here are all the endpoints for the List API

Viewing Items

Any - Returns if any items exist.
Count - Returns how many items we have.
Find - Finds items based on criteria.
Get - Gets an item by id.

Editing Items

Create - Create a new item.
Update - Fully replace an exising item.
Patch - Partially update an exising item.

Removing Items

Remove - Remove an exising item.
Restore - Restore a removed item.

History

History - View an item's history.
Preview Rollback - Preview a rollback, before committing it.
Rollback Version - Rollback to a previous version.

Publishing

Publish - Publish an item.
Unpublish - Unpublish an item.
Is Live - Check if an item is published.

Authentication & Tokens

Both the List and Items API have certain endpoints that require a user token to interact with our content.

If we try to view unpublished items, edit an item, or delete something, Jangle needs to verify that we are an actual user in the system.

Otherwise, anyone could hit these URLs and ruin our day!

(The Authentication API has endpoints for retrieving a valid user token.)

How to provide a token to Jangle API

Protected endpoints will check these places for a user token:

Authorization header, with the Bearer schema (recommended)
```
 Authorization: Bearer our-token
```
As a query parameter in your URL (for testing)
```
 GET /api/lists/authors?token=our-token
```

Any

GET /api/lists/:name/any

Note: If provided a user token, this will work with all items. Without a token, this will only work with published items.

Options

where - a JSON object filtering results. Uses the MongoDB query selector format.

Examples

GET /api/lists/people/any
GET /api/lists/people/any?where={ "name": "Ryan" }

Returns

If any items were found:

{
	"error": false,
	"message": "Found some items.",
	"data": true
}

If no items were found:

{
	"error": false,
	"message": "No items found.",
	"data": false
}

Count

GET /api/lists/:name/count

Note: If provided a user token, this will work with all items. Without a token, this will only work with published items.

Options

where - a JSON object filtering results. Uses the MongoDB query selector format.

Examples

GET /api/lists/people/count
GET /api/lists/people/count?where={ "age": { "$gte": 24 } }

Returns

If any items were found:

{
	"error": false,
	"message": "Found 1 item.",
	"data": 1
}

If no items were found:

{
	"error": false,
	"message": "Found 0 items.",
	"data": 0
}

Find

GET /api/lists/:name

Finds items, returning them in a paginated list. (Max page size is 25)

Note: If provided a user token, this will work with all items. Without a token, this will only work with published items.

Options

where - a JSON object filtering results. Uses the MongoDB query selector format.

select - a list of fields you are interested in returning. Uses Mongoose's select format.

populate - an object using the Mongoose populate format. (Useful for getting related items in one query.)

sort - The field or fields you want to sort by. Uses the Mongoose sort format.

page - The page number to return, defaults to 1.

Examples

GET /api/lists/people
GET /api/lists/people?select=name,age
GET /api/lists/people?where={ "age": { "$gte": 18 } }
GET /api/lists/people?sort=name
GET /api/lists/people?populate=friends
GET /api/lists/people?page=2

Returns

If items were found:

{
	"error": false,
	"message": "Found 30 items.",
	"data": {
		total: 30,
		items: [
			{ /* 1 */ },
			{ /* 2 */ },
			{ /* 3 */ },
			{ /* 4 */ },
			/*...*/
			{ /* 25 */ }
		]
	}
}

If no items were found:

{
	"error": false,
	"message": "Found 0 items.",
	"data": {
		total: 0,
		items: []
	}
}

Get

GET /api/lists/:name/:id

Get an item with the provided id.

Note: If provided a user token, this will work with all items. Without a token, this will only work with published items.

Options

select - a list of fields you are interested in returning. Uses Mongoose's select format.

populate - an object using the Mongoose populate format. (Useful for getting related items in one query.)

Examples

GET /api/lists/people/12345
GET /api/lists/people/12345?select=name,age
GET /api/lists/people/12345?populate=friends

Returns

If the item was found:

{
	"error": false,
	"message": "Item found!",
	"data": {
		"name": "Ryan",
		/*...*/
	}
}

If no items were found:

{
	"error": false,
	"message": "Could not find that item.",
	"data": null
}

Create

POST /api/lists/:name

Create a new, unpublished item in the specified list.

The item should be provided in the body of the POST request.

Note: Requires a user token.

Example

{
	"name": "Ryan",
	"age": 24
}

Returns

If the item was successfully created:

{
	"error": false,
	"message": "Item created!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 24,
		"jangle": { "version": 1, /*...*/ }
	}
}

If the item could not be created:

{
	"error": true,
	"message": "Missing required fields: name.",
	"data": null
}

Update

PUT /api/lists/:name/:id

Update an existing item in the specified list.

The full item should be provided in the body of the PUT request.

Note: Requires a user token.

Example

{
	"name": "Ryan",
	"age": 25
}

Returns

If the item was successfully updated:

{
	"error": false,
	"message": "Item updated!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 25,
		"jangle": { "version": 2, /*...*/ }
	}
}

If the item could not be updated:

{
	"error": true,
	"message": "Missing required fields: age.",
	"data": null
}

Patch

PATCH /api/lists/:name/:id

Partially update an existing item in the specified list.

Only the updated fields should be provided in the body of the PATCH request.

Note: Requires a user token.

Example

{
	"age": 26
}

Returns

If the item was successfully updated:

{
	"error": false,
	"message": "Item updated!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 26,
		"jangle": { "version": 3, ... }
	}
}

If the item could not be updated:

{
	"error": true,
	"message": "age must be a number.",
	"data": null
}

Remove

DELETE /api/lists/:name/:id

Remove an existing item in the specified list.

The item can be recovered later, this just removes it from our list.

Note: Requires a user token.

Example

DELETE /api/lists/people/12345

Returns

If the item was successfully removed:

{
	"error": false,
	"message": "Item removed!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 26,
		"jangle": { "version": 3, /*...*/ }
	}
}

If the item could not be created:

{
	"error": true,
	"message": "age must be a number.",
	"data": null
}

Restore

PUT /api/lists/:name/:id/restore

Restores an existing item that was deleted, from the specified list.

Note: Requires a user token.

Returns

If the item was successfully restored:

{
	"error": false,
	"message": "Item restored!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 26,
		"jangle": { "version": 5, ... }
	}
}

If the item could not be restored:

{
	"error": true,
	"message": "Could not find item.",
	"data": null
}

History

GET /api/lists/:name/:id/history

Shows the history of an existing item from the specified list.

Note: Requires a user token.

Example

GET /api/lists/people/12345/history

Returns

If the item was found:

{
	"error": false,
	"message": "Found the item's history.",
	"data": [
		{ /*...*/ },
		{ /*...*/ },
		{ /*...*/ },
		{ /*...*/ }
	]
}

If the item could not be found:

{
	"error": true,
	"message": "Could not find item.",
	"data": null
}

Preview Rollback

GET /api/lists/:name/:id/preview/:version

Preview the rollback of an existing item to a previous version.

Note: Requires a user token.

Example

GET /api/lists/people/12345/preview/2

Returns

If the version was found:

{
	"error": false,
	"message": "Previewing rollback!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 25,
		"jangle": { "version": 2, /*...*/ }
	}
}

If the item's rollback could not be previewed:

{
	"error": true,
	"message": "Could not find version 100.",
	"data": null
}

Rollback

POST /api/lists/:name/:id/rollback/:version

Rollback an existing item to a previous version.

Note: Requires a user token.

Example

POST /api/lists/people/12345/rollback/2

Returns

If the version was successfully rolled back:

{
	"error": false,
	"message": "Person rolled back successfully!",
	"data": {
		"_id": 12345,
		"name": "Ryan",
		"age": 25,
		"jangle": { "version": 2, /*...*/ }
	}
}

If the item could not be rolled back:

{
	"error": true,
	"message": "Could not find version 100.",
	"data": null
}

Publish

PUT /api/lists/:name/:id/publish

Publish an existing item.

Note: Requires a user token.

Example

PUT /api/lists/people/12345/publish

Returns

If the item was successfully published:

{
	"error": false,
	"message": "Person published successfully!",
	"data": {
		"name": "Ryan",
		"age": 25
	}
}

If the item could not be published:

{
	"error": true,
	"message": "Could not find item.",
	"data": null
}

Unpublish

PUT /api/lists/:name/:id/unpublish

Unpublish an existing item.

Note: Requires a user token.

Example

PUT /api/lists/people/12345/unpublish

Returns

If the item was successfully unpublished:

{
	"error": false,
	"message": "Person unpublished successfully!",
	"data": {
		"name": "Ryan",
		"age": 25
	}
}

If the item could not be unpublished:

{
	"error": true,
	"message": "Could not find item.",
	"data": null
}

Is Live

GET /api/lists/:name/:id/is-live

Determine if an item is currently published.

Example

GET /api/lists/people/12345/is-live

Returns

If the item is published:

{
	"error": false,
	"message": "Person is published.",
	"data": true
}

If the item is not published:

{
	"error": false,
	"message": "Person is not published.",
	"data": false
}

If the item could not be found:

{
	"error": true,
	"message": "Could not find item.",
	"data": null
}

Schema

GET /api/lists/:name/schema

Get information about a list's structure and options.

Useful for rolling your own CMS.

Example

GET /api/lists/people/schema

Returns

If the list exists:

{
	"error": false,
	"message": "Schema found.",
	"data": {
    "name": "Person",
    "slug": "people",
    "labels": {
      "singular": "Person",
      "plural": "People"
    },
		"fields": [
			{
				"name": "name",
				"label": "Name",
				"type": "String",
				"default": "",
        "required": true
      },
			{
				"name": "age",
				"label": "Age",
				"type": "Number",
				"default": "",
        "required": true
      },
			{
				"name": "friend",
				"label": "Friend",
        "type": "ObjectId",
        "ref": "Person",
				"default": "",
        "required": true
      }
    ]
	}
}

If the list could not be found:

{
	"error": true,
	"message": "List not found.",
	"data": null
}

@jangle/api

Jangle API

Overview

Authentication API

Can Sign Up

Example

Returns

Sign Up

Body

Example:

Returns

Sign In

Body

Example:

Returns

List API

Overview

Authentication & Tokens

How to provide a token to Jangle API

Any

Options

Examples

Returns

Count

Options

Examples

Returns

Find

Options

Examples

Returns

Get

Options

Examples

Returns

Create

Example

Returns

Update

Example

Returns

Patch

Example

Returns

Remove

Example

Returns

Restore

Returns

History

Example

Returns

Preview Rollback

Example

Returns

Rollback

Example

Returns

Publish

Example

Returns

Unpublish

Example

Returns

Is Live

Example

Returns

Schema

Example

Returns

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Weekly Downloads