[WIP] API Documentation

Hannah Wolfe edited this page Jun 30, 2015 · 19 revisions

Attention: The API is not publicly accessible at the moment. Please see https://github.com/TryGhost/Ghost/issues/4004 for further details on how OAuth is going to be used to control access to the API.


Skip to:

Design

Ghost's JSON API was originally designed to loosely follow the JSON-API spec, back before the spec reached 1.0. However, the specialist requirements of Ghost's API means that the JSON-API response format is not a good fit and so the two have diverged heavily. The following section attempts to quantify the key principles we hold to in our API design.

The majority of this document talks about using the Ghost API via HTTP. Ghost's API can also be consumed in method call form, and has several abstractions, including the {{#get}} helper used in themes. The core API is identical in all cases.

RESTful

Ghost's API is RESTful:

  • HTTP verbs are mapped to BREAD actions
  • Endpoints represent resources and are therefore always nouns
  • When adding or editing (POST/PUT) an object representing the full resource is sent as the request body
  • HTTP error codes are used correctly as often as possible
  • There is inconsistency in the API with regard to singular vs plural forms of the resource names
  • The API does not currently support PATCH or partial edits of any kind

E.g. Creating a new tag would be done with `POST /tags/

  • HTTP calls can also be made internally using a method call (also available to internal apps via a proxy which handles authorisation).

For method calls, HTTP verbs are mapped to BREAD functions:

E.g. GET /tags/ can be called internally as tags.browse()

  • The first argument to any method should be the same as the request body over HTTP, if there is one.
  • The last argument to any method should be the parameters, structured as a JSON object.
  • There can be at most two arguments.

E.g. GET /tags/3/ called internally would be tags.read({id: 3})

Request/Response Format

All requests and responses in the API use JSON to send and receive data.

The JSON always has a top level key which either matches the resource of the endpoint being sent/received from, or it has a top level errors key. The response may also return a meta key with extra information.

Top level errors or resources keys e.g. posts always contain an array of objects, even if there is a single object being sent or received.

The top level meta key contains an object with several sub-keys including pagination.

Parameters

Parameters can be sent to the API over HTTP in two forms: URL and query. URL parameters are included in the endpoint E.g. GET /posts/2/ includes an id parameter. Query parameters are included in the query string E.g. GET /posts/?limit=5.

When using the API via a method call, both types of parameters are provided in the options object, which is always the last argument passed to the function.

E.g GET /posts/2/ becomes posts.read({id: 2}) and GET /posts/?limit=5 becomes posts.read({limit: 5}).

Errors

The response format for errors is an errors top level key, which contains an array of error objects.

Each error object must contain a message and an errorType

When returned over HTTP, the HTTP status code matches the error type, E.g. the following response would have a 404 status code:

{"errors":
  [
    {
      "message":"Post not found",
      "errorType":"NotFoundError"
    }
  ]
}

Endpoints

Posts

  • GET /ghost/api/v0.1/posts - get all posts
    • Options:
      • page - pagination (default: 1)
      • limit - number of posts per page (all or an integer. default: 15)
      • status - status of the page (all, published, draft)
      • staticPages - include static pages (default: false)
  • POST /ghost/api/v0.1/posts - add new post
  • GET /ghost/api/v0.1/posts/:id - get post with id
  • GET /ghost/api/v0.1/posts/slug/:slug - get post with slug
  • PUT /ghost/api/v0.1/posts/:id - update post with id
  • DELETE /ghost/api/v0.1/posts/:id - delete post with id

DB

  • GET /ghost/api/v0.1/db/ - export database
  • POST /ghost/api/v0.1/db/ - import database
  • DELETE /ghost/api/v0.1/db/ - delete content from database

Notifications

  • DELETE /ghost/api/v0.1/notifications/:id - delete notification
  • POST /ghost/api/v0.1/notifications/ - add new notification

Settings

  • GET /ghost/api/v0.1/settings/ - get all settings
    • Options:
      • type (blog, app, theme)
  • GET /ghost/api/v0.1/settings/:key/ - get setting with key
  • PUT /ghost/api/v0.1/settings/ - update settings

Tags

  • GET /ghost/api/v0.1/tags/ - get all tags

Users

  • GET /ghost/api/v0.1/users/ - get all users
  • GET /ghost/api/v0.1/users/:id/ - get user with id (id=me would be the current user)
  • GET /ghost/api/v0.1/users/slug/:slug/ - get user with slug
  • GET /ghost/api/v0.1/users/email/:email/ - get user with email
  • PUT /ghost/api/v0.1/users/:id/ - update user with id

Post

The Post Object

Attributes

  • id: integer
  • uuid: string
    Unique identifier generated automatically as UUIDv4.
  • title: string
    Title of your blog post.
  • slug: string
    Automatically generated unique slug that is based on the title of your blog post (e.g.: 'Test Post' will become 'test-post').
  • status: string
    Possible values are draft and published. status has influence on who can see your post and if it is shown on the frontpage of your blog. Defaults to draft.
  • markdown: string
    Markdown of your post.
  • html: string
    HTML of your post generated from markdown.
  • image: string
    Not currently used.
  • featured: boolean
    Indicate a featured post. Defaults to false.
  • page: boolean
    Indicate if the post is a page. Defaults to false.
  • language: string
    Language of the post. Not currently used. Defaults to en_US. Language codes used as primary subtags are from ISO 639-1. Country codes used as secondary subtags are from ISO 3166. Primary and secondary tag are concatenated with an underscore.
  • meta_title: string
    Not currently used.
  • meta_description: string
    Not currently used.
  • author: integer, user - includeable
    Author of the post. By default the creator is used as initial author.
  • created_at: string
    ISO 8601 date and time when the post was created.
  • created_by: integer, user - includeable
    User who created the post.
  • updated_at: string
    ISO 8601 date and time when the post was last updated.
  • updated_by: integer, user - includeable
    User who last updated the post
  • published_at: string
    ISO 8601 date and time when the post was published.
  • published_by: integer, user - includeable
    User who published the post
  • tags: array of objects, tags
    Tags associated with the post.

Example Post Object

{
    posts: [
        {
            status: "published",
            id: 1,
            uuid: "ec630e45-3342-4d7f-a24c-e448263c975b",
            title: "Welcome to Ghost",
            slug: "welcome-to-ghost",
            markdown: "",
            html: "",
            image: null,
            featured: false,
            page: false,
            language: "en_US",
            meta_title: null,
            meta_description: null,
            author: 1,
            created_at: "2014-04-15T12:36:28.353Z",
            created_by: 1,
            updated_at: "2014-04-15T12:36:28.353Z",
            updated_by: 1,
            published_at: "2014-04-15T12:36:28.363Z",
            published_by: 1,
            tags: [{ ... }]
        }
    ]
}

Paginated List of Post Objects

Attributes

  • posts: array, post
  • meta: object
    Meta information for the result returned.
  • pagination: object
    Pagination information.
  • page: integer
    Number of the current page
  • limit: integer
    Number of posts per page
  • pages: integer
    Number of pages
  • total: integer
    Number of total posts
  • next: integer
    Number of next page, null if not available.
  • prev: integer
    Number of previous page, null if not available.

Example Paginated List of Post Objects

{
    posts: [{...}],
    meta: {
        pagination: {
            page: 1,
            limit: 15,
            pages: 1,
            total: 1,
            next: null,
            prev: null
        }
    }
}

Retrieve an Existing Post

Retrieves an existing post. In order to get a post the id or slug are needed to identify the post. The information returned when creating, updating or deleting is identical to retrieving a post.

Usage

API Example
Internal API api.posts.read({id: id})
HTTP Route GET /ghost/api/v0.1/posts/{id}/
GET /ghost/api/v0.1/posts/slug/{slug}/

Arguments

  • id or slug: required
    ID of the post you would like to retrieve.

Permissions

Admin Editor Author NoAuth
read all posts read all posts read posts with status published
or that were created by the user
read posts with status published

Retrieve a Paginated List of Existing Posts

Retrieves a paginated list of post that exist in your database. By default only published posts are returned. It is possible to modify the filter using the status argument.

Usage

  • api.posts.browse({status: 'draft'})
  • GET /ghost/api/v0.1/posts/?status=draft

Arguments

  • status: optional
    Allowed values are draft, published and all.
  • staticPages: optional
    Include posts where the page attribute is true. Allowed values are true, false and all.

Permissions

Admin Editor Author NoAuth
read all posts read all posts read posts with status published
or that were created by the user
read posts with status published

Create a new post

Create a new post. Tags that are sent with a new post are created if they don't exist and linked to the newly created post. The newly created post object is returned.

Usage

API Example
Internal API api.posts.add(object, options)
HTTP Route POST /ghost/api/v0.1/posts/

Arguments

  • object: mandatory
    Data of the post that is going to be created. The object is expected to be a valid post object with mandatory and optional properties.

Mandatory post properties:

  • title
  • markdown

Optional post properties:

  • slug
  • status
  • image
  • featured
  • page
  • language
  • meta_title
  • meta_description
  • author

  • options: optional
    TBD

Permissions

Admin Editor Author NoAuth
create post create post create post -

Edit an existing post

Update a post that already exists. In order to update a post the id is needed to identify the post. The edited post object is returned.

Usage

API Example
Internal API api.posts.edit(object, options)
HTTP Route PUT /ghost/api/v0.1/posts/<id>/

Arguments

  • object: mandatory
    A valid post object with properties that should be updated.

Mandatory post properties:

  • id

Updatable post properties:

  • slug
  • title
  • markdown
  • status
  • image
  • featured
  • page
  • language
  • meta_title
  • meta_description
  • author
  • published_at

  • options: optional
    TBD

Permissions

Admin Editor Author NoAuth
edit all posts edit all posts edit all posts that were
create by the user
-

Delete a post

Delete an existing post. In order to delete a post the id is needed to identify the post. The deleted post object is returned.

Usage

API Example
Internal API api.posts.destroy(options)
HTTP Route DELETE /ghost/api/v0.1/posts/<id>/

Arguments

  • options: optional
    TBD

Permissions

Admin Editor Author NoAuth
delete all posts delete all posts delete all posts that were
create by the user
-

Tag

The Tag Object

Attributes

  • id: increments
  • uuid: string
    Unique identifier generated automatically as UUIDv4.
  • name: string
    Name of the tag.
  • slug: string
    Automatically generated unique slug that is based on the name of your tag (e.g.: 'Test Tag' will become 'test-tag').
  • description: string
    Not currently used.
  • parent_id: integer
    Not currently used.
  • meta_title: string
    Not currently used.
  • meta_description: string
    Not currently used.
  • created_at: dateTime
    Remark about date/time
  • created_by: integer
    Includeable when implemented
  • updated_at: dateTime
    Remark about last updated date/time.
  • updated_by: integer
    User id of last update author.

Example Tag Object

{
      tags: [{
            "id": 1,
            "uuid": "c912cb47-fe10-4120-aca3-19feb1a931d6",
            "name": "Getting Started",
            "slug": "getting-started",
            "description": null,
            "parent_id": null,
            "meta_title": null,
            "meta_description": null,
            "created_at": "2014-03-12T17:04:00.819Z",
            "created_by": 1,
            "updated_at": "2014-03-12T17:04:00.819Z",
            "updated_by": 1
      }]
}

Usage

  • api.tags.browse()
  • GET /ghost/api/v0.1/tags/

User

The User Object

Attributes

  • id: integer
  • uuid: string
    Unique identifier generated automatically as UUIDv4.

Example User Object

{
    users: [
        {

        }
    ]
}