Announcing the Cosmic REST API v2, New Docs

We are excited to introduce Cosmic REST API v2 (alpha). The API has been rebuilt from the ground up to be lighter, faster, with lots of new features to make building Cosmic-powered apps even better.

Along with this release, we've built a brand new documentation site to help you learn more about all the new features. We recommend you start there to get all the latest and greatest in this release. Read below to get a breakdown of the new features, improvements, and changes.

New Features

• Nested metadata props are now possible without limit. See examples of nested props.
• No depth limit for Object relationships. The only limit is the prevention of infinite recursion.
• We now offer a Postman collection to review and demo all REST API methods.
• You can now use the after param for Object pagination.
• We now have endpoints for Metafields and Media Folders to do CRUD operations directly.

Improvements

• Lighter codebase, faster endpoints. In some cases, endpoint response times are up to 50% faster (non-cached).
• Better endpoint structures that follow standard REST conventions such as POST /resources, GET /resources/:resource_id, etc.
• Consistent error responses with verbose messages.
• The Select Dropdown Metafield now includes both key and value in the API response.

Changes

• _id has been changed to id.
• type_slug has been changed to type.
• status can now either be published or any (which returns latest Object version draft or published).
• query is now the primary method for fetching and filtering Objects (Advanced Queries from v1). See Queries and Logic for examples.
• Single Objects must now be fetched using id. To fetch by slug, you will need to use query.
• write_key will now be required in the request header as Authorization Bearer.
• metafields are hidden by default.
• Stricter user input requirements. No additional fields are possible in the body for POST and PATCH requests.
• There is a new, more secure token authentication strategy.

Next Steps

Read the docs to learn more about all the updates and improvements. We would appreciate your input as we get the REST API v2 ready for production. If you have any comments or questions, please drop them in the comments below or in our Slack channel.

- Cosmic Team