@jangle/api
Advanced tools
A RESTful API built on top of Jangle Core.
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:
Creating users, signing in, getting tokens.
GET/api/auth/can-sign-up
Find out if sign-up is allowed. Useful for sign-up / sign-in screens.
GET /api/auth/can-sign-up
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
}
POST/api/auth/sign-up
Create a new user for our Jangle instance, if no other users exist in the system.
name - The display name for the new user.email - The email for the new user.password - The password for the new user.{
"name": "Ryan",
"email": "ryan.nhg@gmail.com",
"password": "jangleIsEasy"
}
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
}
GET/api/auth/sign-in
Sign in an existing Jangle user.
"Why is sign in a GET request?"
Signing in with Jangle doesn't modify anything, all it does is gets you a token.
If you are curious about HTTP verbs, like GET, POST, PUT,PATCH, and DELETE, here is an awesome explanation of when to use which.
email - The email address of the user.password - The password of the user.GET /api/auth/sign-in?email=ryan.nhg@gmail.com&password=jangleIsEasy
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
}
Viewing and updating items in Jangle Lists.
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
Editing Items
Removing Items
History
Publishing
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.)
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
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.
where - a JSON object filtering results. Uses the MongoDB query selector format.
GET /api/lists/people/any
GET /api/lists/people/any?where={ "name": "Ryan" }
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
}
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.
where - a JSON object filtering results. Uses the MongoDB query selector format.
GET /api/lists/people/count
GET /api/lists/people/count?where={ "age": { "$gte": 24 } }
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
}
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.
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.
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
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/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.
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.)
GET /api/lists/people/12345
GET /api/lists/people/12345?select=name,age
GET /api/lists/people/12345?populate=friends
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
}
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.
{
"name": "Ryan",
"age": 24
}
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
}
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.
{
"name": "Ryan",
"age": 25
}
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/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.
{
"age": 26
}
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
}
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.
DELETE /api/lists/people/12345
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
}
PUT/api/lists/:name/:id/restore
Restores an existing item that was deleted, from the specified list.
Note: Requires a user token.
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
}
GET/api/lists/:name/:id/history
Shows the history of an existing item from the specified list.
Note: Requires a user token.
GET /api/lists/people/12345/history
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
}
GET/api/lists/:name/:id/preview/:version
Preview the rollback of an existing item to a previous version.
Note: Requires a user token.
GET /api/lists/people/12345/preview/2
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
}
POST/api/lists/:name/:id/rollback/:version
Rollback an existing item to a previous version.
Note: Requires a user token.
POST /api/lists/people/12345/rollback/2
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
}
POST/api/lists/:name/:id/publish
Publish an existing item.
Note: Requires a user token.
POST /api/lists/people/12345/publish
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
}
POST/api/lists/:name/:id/unpublish
Unpublish an existing item.
Note: Requires a user token.
POST /api/lists/people/12345/unpublish
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
}
GET/api/lists/:name/:id/is-live
Determine if an item is currently published.
GET /api/lists/people/12345/is-live
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
}
GET/api/lists/:name/schema
Get information about a list's structure and options.
Useful for rolling your own CMS.
GET /api/lists/people/schema
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
}
FAQs
A RESTful API built on top of Jangle Core.
The npm package @jangle/api receives a total of 13 weekly downloads. As such, @jangle/api popularity was classified as not popular.
We found that @jangle/api demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.