kyuknis
September 15, 2018, 12:02am
1
Greetings. I was wondering if I could get an update on the status of the Ghost API, or at least a synopsis of it’s current roadmap. I’m working on creating an iOS app for Ghost in Swift, and I’m happy to do this but I want to have something a little less “hack-y” in place before I put in a lot of work on the providers and models. Specifically I’m asking about the authentication mechanism, as the parts where data is actually retrieved with an authentication key appears to be close-enough to done for my purposes. Perhaps this is more done than the documentation lets on? Ghost has proven to be a great platform, and I hope to contribute to a bright future for the platform on the Apple ecosystem.
Kevin
September 17, 2018, 8:50am
2
@kyuknis it depends if you are trying to write to the API or just read public content. If you are only trying to read public content then you can follow the guide here https://api.ghost.org/docs/ajax-calls-from-an-external-website (although as you’re connecting from an iOS app you don’t need to worry about the trusted domains part).
If you are trying to write by using the private API then the only method is to go through user authentication to get an access/refresh token. The private API is not documented, the best way to examine how it works is to inspect the network requests that the admin area makes (it’s an SPA that uses the private API so you can use web inspector for this).
We are currently in the middle of re-working the API and splitting it into two separate APIs - content and admin - along with new authentication mechanisms. You can follow along on these issues:
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.
system
Closed
October 1, 2018, 8:50am
3
This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.