Just Write API

A simple API for creating and organizing content via JSON files. No database required, so it works great as a back-end for static site generation.

Installation

Snag the package from NPM:

npm install --save just-write-api

Standalone Usage

The Just Write API can run as a server on Node.js.

Use it programmatically:

const {server} = require('just-write-api');
server([options]);

Or start it from the command line:

just-write-api [--content-dir content][--host localhost][--port 8001]

Usage as an Express Router

The API endpoints can also be included in an existing Express server. Simply import endpointRouter from the module and use it as you would any other Express router.

const express = require('express');
const {endpointRouter} = require('just-write-api');

const app = express();

app.use(endpointRouter());

// or, as a nested route
app.use('/api', endpointRouter());

Core Concepts

The Just Write API concerns itself with two things: pages and tags.

Pages

Pages could be blog posts, pages on a website, or documents like recipes or book chapters.

A page entity consists of a title and content property and any optional metadata you'd like to associate with it. They're stored and accessed as JSON.

Minimally

{
    "title": "A Minimal Page Example",
    "content": "This is page content."
}

Elaborately

{
    "title": "A Realistic Example for a Static Site Generator",
    "content": "# My Markdown Content!",
    "tags": "a123, b456",
    "created": "December 27, 2017",
    "updated": "January 3, 2018",
    "author": "Peter Parker"
}

Tags

Tags are organizational units of the Just Write API. They're how pages are classified.

Tag entities consist of a name property and any additional metadata; just as with pages, they're stored and accessed as JSON.

Minimally

{
    "name": "My Tag"
}

Elaborately

{
    "name": "A Realistic Tag",
    "description": "A classification relevant to organizing pages.",
    "created": "January 3, 2018",
    "related": "tagId123,tagId456"
}

No Categories?

No. No categories.

Tags, with other tags, can represent any hierarchy: categories, sub-categories, keywords, etc. Information architecture is unopinionated so you can organize your content however you like using logical dis/conjunctions.

Endpoints

/pages

| HTTP Method | Required | Returns | Description | |-------------|----------|---------|-------------| | GET | | Array of objects | Get a listing of all page entities; supports filters | | POST | title, content | Object | Create a new tag entity and returns the newly created resource, including its generated UUID and creation timestamp |

/pages/tagged/:tagId1[,tagId2,...tagIdN]

| HTTP Method | Required | Returns | Description | |-------------|----------|---------|-------------| | GET | | Array of objects | Retrieve pages tagged by the comma-delimited list of tag IDs. Currently only supports conjunctions of tags, but does support filters

/page/:id

| HTTP Method | Required | Returns | Description | |-------------|----------|---------|-------------| | DELETE | | Array of objects | Deletes a specific page resource and returns the new listing of pages | | GET | | Object | Retrieve data for a specific page resource | | PUT | title, content | Object | Update a specific page resource and return the updated resource with a timestamp |

/tags

| HTTP Method | Required | Returns | Description | |-------------|----------|---------|-------------| | GET | | Array of objects | Get a listing of all tag entities; supports filters | | POST | name | Object | Create a new tag entity and returns the created resource, including its generated UUID |

/tag/:id

| HTTP Method | Required | Returns | Description | |-------------|----------|---------|-------------| | GET | | Object | Retrieve data on a specific tag entity | | PUT | name | Object | Update a specific tag entity and return the updated tag | | DELETE | | Array of objects | Delete a specific tag entity and return the updated list of tag entities |

Filters

The API supports filters on specified requests -- namely GETs -- to narrow down a results set. Filters are passed as URI query parameters to the request.

Example

GET /pages?author=Jack
// returns page entities whose author field matches 'Jack'

Currently, filters are only supported for entity field subsets.

Configuration Options

The API has a minimal set of configuration options. All of them are optional.

| Property | Command Line Flag | Default | Description | |----------|-------------------|---------|-------------| | contentDir | --content-dir | content | Folder where content is created and managed in the current working directory | | host | --host | localhost | Host name where the API server will run. Not available when using endpointRouter mode | | port | --port | 8001 | Port the API server will run on. Not available when using endpointRouter mode |