Kevin
September 17, 2018, 8:42am
2
The current v0.1API requires a mobiledoc field from which to generate the html and plaintext content from. You’re using a private API that is not documented or designed for external use so there’s not much information available for what you’re trying to do.
If you can wait I would suggest waiting for the new v2 API and authentication mechanisms to land:
opened 11:51PM - 12 Sep 18 UTC
closed 03:31PM - 25 Oct 18 UTC
server / core
api
feature
## Why API Versioning?
- We want to avoid that external clients break if they… update their Ghost version. You either need to update the client first or your blog. You will always break clients for a period of time. With API versioning there’s no pressure to update immediately. You can even update to a new major version of Ghost without breaking your clients.
- The public API is in beta since years now and we would like to work on a stable public API version.
- The public and private API live on the same url (`/api/v0.1/`), but they both have different characteristics e.g. authentication, response values, restrictions. Having both on the same url makes it harder to maintain the code.
- We would like to overhaul our current authentication strategies. Covered by #9865.
## Future of Ghost
In the near future we would like to achieve a 3 way split to make Ghost more customisable and flexible.
These are: Ghost Core, SDK’s and Clients.
### Ghost Core
Should become API centric in the future, future. That means, our suite of APIs will be first class citizens allowing Ghost to function as a headless CMS.
### SDK
Our suite of tools intended to help developers make use of APIs in their clients. SDKs should offer commonly used functionality that works on top of the data provided by an API in the form of small, reusable modules or components.
### Clients
The ultimate API consumers. Some are interacted with by users, some by computers. They share common needs and so should be as small as possible, relying on shared code from the SDKs to solve common problems.
## Reference Material / Research
- Facebook
- https://developers.facebook.com/docs/graph-api/changelog/breaking-changes
- They use e.g. v3.1 versioning notation.
- Reason for that is that want to lists the features they have added in the current major version. At Ghost we can update our docs based on the current minor Ghost version.
- GitHub
- https://developer.github.com/v3/versions/
- They use major versions only e.g. v1, v2
- They use headers to transmit the version e.g. Accept: `application/vnd.github.v3+json`
- Stripe
- https://stripe.com/blog/api-versioning
- https://stripe.com/docs/api#versioning
- They use a mixture.
- Dated versioning - the date when the API version was released.
- in a `Stripe-Version` header
- `/v1/` as standard API endpoint
- Contentful
- https://www.contentful.com/developers/docs/references/content-management-api/#/introduction/api-versioning
- They use major versions only e.g. v1, v2.
- `Content-Type: application/vnd.contentful.management.v1+json`
- Restify
- http://restify.com/docs/home/
- Uses `Accept-Version: *`
- General API change management guide and very interesting reads:
- https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/
- https://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
- https://www.mnot.net/blog/2012/12/04/api-evolution
- https://apigility.org/documentation/api-primer/versioning
- https://blog.goodapi.co/api-maturity-fb25560151a3
- http://www.ben-morris.com/rest-apis-dont-need-a-versioning-strategy-they-need-a-change-strategy/
- http://apiux.com/2013/05/14/api-versioning/
- https://projects.tmforum.org/wiki/display/API/Entity+Versioning+and+Lifecycle+Management
- https://cloudplatform.googleblog.com/2018/03/API-design-which-version-of-versioning-is-right-for-you.html
- https://yalantis.com/blog/api-versioning-with-ruby-on-rails/
- https://github.com/Microsoft/aspnet-api-versioning/issues/70
## Main Goals
- Rename Public API to Content API and Private API to Admin API
- API versioning for the Content and Admin API
- First stable Content API
- Admin API goes into Beta
- Do not break v0.1 API
- Support three API version at a time
## API Versions
Based on the research material, we have decided to go with major versions only.
Examples for major versions: v1, v2, v3, v4 etc.
Reasons why we go with major versions:
- Research material showed us that this is a very common approach.
- We don’t want to force our clients to update their API version with any new feature/addition.
The Ghost **active API version** should equal **the current major** Ghost release. The latest Ghost major version is Ghost 2.x, that means we will introduce API version `v2`.
The latest/active API version should add concentrate on adding forwards compatible changes (add features, add routes, add new fields). As soon as we have to introduce breaking changes we have to:
- add a new unstable (alpha/beta) API version
- ensure we don’t break the old API versions
## How does future versioning work?
The basic concept is (3 versions at a time):
- current active version (feature additions)
- stable version
- deprecated version
**Examples**:
Ghost 2.0
- v0.1
- stable
- v2
- active version
- breaking changes allowed initially, from there on only new functionality and forwards compatible
- v3
- we start with v3 as soon as we have breaking changes
- we will release v3 before shipping Ghost 3.0
- v3 becomes alpha/beta in Ghost 2.0
- v3 becomes active in Ghost 3.0
Ghost 3.0
- v0.1
- deprecated, won’t break
- v2
- stable, won’t break
- v3
- active
- new stuff allowed
- breaking changes are not allowed
- v4
- we start with v4 as soon as have to introduce breaking changes, same as above
## Endpoint design
Two new endpoints for `v2` will be introduced:
We have decided to use **url versioning,** because it fits better to Ghost needs.
### Reasons against API headers:
- you can't put a header when accessing the url in the browser
- it's harder to cache public/content api requests when using a header
- if you don't provide an api header, you would fallback to the latest api version, which can create an unintended behaviour for clients
- it's harder to add a header than putting the version into a url
- we want to be explicit
### The actual design
- `/api/v2/content/`
- public, read-only
- v2 becomes active version
- `/api/v2/admin/`
- private, CRUD
- goes into beta
- `/api/v0.1/`
- currently in beta
- becomes “stable”
- won’t break
## Themes are clients
The theme has access to the API layer. It get’s data in and can pull more data from the API using the {{get}} helper. The theme layer is coupled with the actual blog site. They are both one client using the API. All themes currently use the API version v0.1.
We will introduce a new theme configuration option to define which API version you would like to use. This configuration value will probably live in the package.json of a theme. For now, if no api version is configured, we fallback to v0.1.
In the future it might be possible to define the version per helper, but that would be a future improvement.
## Code Challenges
The biggest challenges are:
- come up with a future proof folder structure to support api versioning
- decouple model and api layer
- decide which is shared functionality and which is not
- granular API layers per API versions including serialisers
- make it possible to reduce the maintenance cost for writing tests per API version
opened 08:05PM - 12 Sep 18 UTC
closed 05:49AM - 26 Feb 19 UTC
admin client
server / core
api
feature
We're working towards a new versioned API and making both the public and private… APIs in Ghost first-class citizens. As part of this work we'll be overhauling the authentication methods for the new versioned API endpoints.
- Content API = public content only, equivalent to current public API
- Admin API = all content and settings, equivalent to current private API
Each API will live on a new endpoint and there will be three different authentication methods to access them depending on the API being used and the particular use-case...
- `/admin/`
- User / Password login with session cookie authentication. Used by Ghost-Admin and other admin clients such as the Android app
- API keys with JWT authentication. Used by integrations such as Zapier or custom server-side apps
- `/content/`
- API key authentication using query parameters
As part of the overhaul, the new APIs will have the restrictive and confusing `trusted_domains` and `client_id/client_secret` concepts removed. HTTP access will be deprecated for the Admin API in production until Ghost 3.0 where the Admin API will become HTTPS-only.
We will be providing an SDK for making authenticated requests to the the new API endpoints.
The existing API will be deprecated but will continue to live on `/api/v0.1/` with the current authentication methods until such time as the `0.1` version is fully removed from Ghost. See
https://github.com/TryGhost/Ghost/issues/9866 for details on the new API endpoints and API versioning.
If you can’t wait then you should examine the network requests made by the admin area (it’s an SPA that uses the private API) to determine the required fields and formats.