Ghost/core/server/api
kirrg001 7f7b477ce9 Fixed error message being unclear when admin api keys create posts without authors
refs #10438

- integrations != users
- Ghost's assumption is: if you create a post, the primary author becomes the logged in user
- we have to require authors for integrations
- short fix and needs some more thoughts later
2019-01-31 16:27:56 +01:00
..
shared Added v2 theme controller 2019-01-30 19:45:02 +01:00
v0.1 🐛 Fixed files staying in temp directory after upload is done 2019-01-30 09:24:29 +00:00
v2 Fixed error message being unclear when admin api keys create posts without authors 2019-01-31 16:27:56 +01:00
index.js De-aliased api versions in codebase (#10375) 2019-01-14 19:49:55 +01:00
README.md Added tiny framework to support multiple API versions (#9933) 2018-10-05 00:50:45 +02:00

API Versioning

Ghost supports multiple API versions. Each version lives in a separate folder e.g. api/v0.1, api/v2. Next to the API folders there is a shared folder, which the API versions use.

NOTE: v0.1 is deprecated and we won't touch this folder at all. The v0.1 folder contains the API layer which we have used since Ghost was born.

Stages

Each request goes through the following stages:

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

The framework we are building pipes a request through these stages depending on the API controller implementation.

Frame

Is a class, which holds all the information for API processing. We pass this instance per reference. The target 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
  },
  options: ['include']
  validation: {
    options: {
      include: {
        required: true,
        values: ['tags']
      }
    }
  },
  permissions: true,
  query(frame) {
    return models.Post.edit(frame.data, frame.options);
  }
}
read: {
  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);
  }
}