1
0
mirror of https://github.com/TryGhost/Ghost.git synced 2024-12-22 18:31:57 +03:00
Ghost/ghost/api-framework
Fabien "egg" O'Carroll cfef41cd8f Added support for custom cache key generation
refs https://github.com/TryGhost/Arch/issues/83

This allows endpoints to implement their own key generation, with access to the
frame object they can be smart about key generation and use only options and
context values that are appropriate.
2023-09-19 12:39:50 +07:00
..
lib Added support for custom cache key generation 2023-09-19 12:39:50 +07:00
test Implemented duplicate post functionality () 2023-05-15 09:30:32 +01:00
.eslintrc.js Extracted shared API framework to separate package 2022-08-11 17:44:59 +02:00
index.js Extracted shared API framework to separate package 2022-08-11 17:44:59 +02:00
package.json Updated linting and testing packages 2023-09-01 15:51:17 +02:00
README.md Moved API documentation to api-framework README 2022-08-11 17:44:59 +02:00

API Framework

API framework used by Ghost

Usage

Stages

Each request goes through the following stages:

  • input validation
  • input serialisation
  • permissions
  • query
  • output serialisation

The framework we are building pipes a request through these stages in respect of the API controller configuration.

Frame

Is a class, which holds all the information for request processing. We pass this instance by reference. Each function can modify the original instance. No need to return the class instance.

Structure

{
  original: Object,
  options: Object,
  data: Object,
  user: Object,
  file: Object,
  files: Array
}

Example

{
  original: {
    include: 'tags'
  },
  options: {
    withRelated: ['tags']
  },
  data: {
    posts: []
  }
}

API Controller

A controller is no longer just a function, it's a set of configurations.

Structure

edit: function || object
edit: {
  headers: object,
  options: Array,
  data: Array,
  validation: object | function,
  permissions: boolean | object | function,
  query: function
}

Examples

edit: {
  headers: {
    cacheInvalidate: true
  },
  // Allowed url/query params
  options: ['include']
  // Url/query param validation configuration
  validation: {
    options: {
      include: {
        required: true,
        values: ['tags']
      }
    }
  },
  permissions: true,
  // Returns a model response!
  query(frame) {
    return models.Post.edit(frame.data, frame.options);
  }
}
read: {
  // Allowed url/query params, which will be remembered inside `frame.data`
  // This is helpful for READ requests e.g. `model.findOne(frame.data, frame.options)`.
  // Our model layer requires sending the where clauses as first parameter.
  data: ['slug']
  validation: {
    data: {
      slug: {
        values: ['eins']
      }
    }
  },
  permissions: true,
  query(frame) {
    return models.Post.findOne(frame.data, frame.options);
  }
}
edit: {
  validation() {
    // custom validation, skip framework
  },
  permissions: {
    unsafeAttrs: ['author']
  },
  query(frame) {
    return models.Post.edit(frame.data, frame.options);
  }
}

Develop

This is a monorepo package.

Follow the instructions for the top-level repo.

  1. git clone this repo & cd into it as usual
  2. Run yarn to install top-level dependencies.

Test

  • yarn lint run just eslint
  • yarn test run lint and tests