fossabot/ghost-api

Ghost-API

Introduction

Ghost-API is a server-side wrapper for the v0.1 API of the popular blogging platform Ghost.

Table 'O Contents

• Installation
• Usage
• Instance API
• TokenManager API
• Issues
• Contributing
• Thanks
• License

Installation

Ghost-API is not available on NPM because 1) we want to adhere to Ghost Trademark Policy and 2) this package is not complete. That being said, it is still possible to install ghost-api as a dependency

npm install https://github.com/HexRweb/ghost-api.git --save

Usage

As of now, Ghost-API is only capable of token-related tasks. More functionality will be added in the future, on an as-needed basis. Ghost-API follows Ghost node version guidelines; node v6 & v8 are currently supported.

Requiring the Ghost-API will expose a GhostInstance class. This gives you the ability to easily keep track of multiple Ghost instances that are using the API. To create a GhostInstance,

const GhostInstance = require('ghost-api');
const options = {};
const instance = new GhostInstance(options)

Instance API

constructor

The GhostInstance constructor takes an optional object paramater. This parameter should provide 5 key details:

url - The HTTP URL of the Ghost Instance

username = user (user takes precedence) - The email address of the account to login to {url}

password = pass (pass takes precedence) - The password of the account to login to {url}

client - Client ID used to access the API. Found in the clients table of a working Ghost instance

secret - Client Secret used to access the API. Found in the clients table of a working Ghost instance and corresponds to Client ID

Without these 5 keys, any instance is functionally useless. You can modify any of these values via object assignment (instance[key] = 'new_value').

endpoint(e)

Retrieve an API endpoint. Supports basic object traversal via dot notation (i.e. token.destroy will equate to paths['token']['destroy'])

Returns a relative URL for existing paths, or an object containing all related paths for non-existent paths

urlFor(action)

Generates an absolute URL for endpoint action

getToken

Retrieves a valid oAuth access token for the instance

validate

Verifies the validity of the instance. You should run this before performing any actions to make sure the instance is usable, including the token.

destruct

Destroys the instance. This revokes all known tokens as a courtesy to the Ghost instance.

(static) endpoints

A list of all known and functional endpoints. GhostInstance.prototype.endpoint uses this list.

TokenManager API

TokenManager is responsible for maintaining access and refresh tokens. It has a circular dependency with GhostInstance. While you shouldn't directly access these methods, they are documented for future improvement and feedback. TokenManager, like GhostInstance is a class.

constructor

Takes a required instance parameter. Instance must be an instantiated Instance class

initialize

Initializes the TokenManager instance by logging in to the paired instance. Returns a valid access token.

refresh

Refreshes tokens if necessary. Returns a valid access token.

updateTokens(response)

Takes a parameter (response) which is a parsed JSON object of the the response body of a POST request to get a token

Updates access and refresh tokens locally, and access token expiry. Returns a valid access token

getToken

Returns a valid access token

destroySingleToken(token, auth)

Attempts to delete token from the paired instance. Uses the auth token for authentication

destruct

Attempts to destroy all tokens from the paired related that were created by the TokenManager instance

unsetAccess

Overrides the accessToken. This usually occurs when there was an attempt to destroy a token that failed

tokenIsValid(offset)

Takes an optional offset (defaults to 1000) and determines if the access token will be valid within said offset

urlFor(e)

Alias of this.instance.urlFor(e)

validate

Ensures the access token is still valid

Issues

Got an issue? Question? Comment? Concern? Feel free to create an issue. We'll try and help you out

Contributing

Want to make Ghost-API better? Great! You're appreciated 😄 Feel free to create a PR with your changes. Please make sure all tests pass (npm test), coverage stays high (we'd prefer 100% but it's understandable if that's not possible) and documentation stays useful and relevant.

Thanks

This project wouldn't have been possible without the existence of the Ghost Foundation and all of the contributors who make it successful. A lot of the boilerplate code (i.e. package file, tests) was created with influence from the Ghost CLI

License

This project, just like Ghost, is licensed under the MIT License