Create a prismic.io API Client

Here we walk through everything you need to do when creating a prismic.io API client for a new technology or framework.

prismic.io kits

Before anything, make sure you check out which technologies and frameworks already have a prismic.io kit on our prismic.io libraries & tools list. We've already covered most of the major technologies, so what you need is very likely to be there!

If it isn't, don't panic! prismic.io is designed to work well with all technologies, and it's very simple to create a new prismic.io library. In this case, we highly encourage you to create your own library and let us know about it. We will reference your kit on the prismic.io developers portal, and it will give a precious hand to other developers using the same technology as you.

To ensure that your new kit is compatible with all of prismic.io's future features we have established the following guidelines to use when developing your API client.

Definitions

We differentiate 3 types of code "libraries" for prismic.io:

  • API Client: It is a minimal library, providing binding for a specific programming language to the prismic.io REST API. It can be embedded as a dependency in any project of that language.
  • Framework: A starter project is a simple prismic.io project created for a specific technology and a specific development framework. It can be used as a foundation for any new prismic.io project. It depends on a prismic.io development kit and on other external libraries that make it easier to work with a specific development framework.
  • Samples: A sample is a complete application written in a specific technology. It is based on an existing starter project but demonstrates more sophisticated ways to query and to display the content.

Existing libraries and licenses

All our official libraries (development kits, starter project and examples) are available from our GitHub page at https://github.com/prismicio. All are open source and licensed under the Apache 2 license.

If you want to create your own library (whether a development kit, a starter project or a full-featured example), you are free to host it yourself, or to ask us to have it hosted by the prismic.io official organization. If it matches the guidelines, we'll publish it on our prismic.io developers portal, either way.

API Client kits

A few rules:

  1. A development kit is written for a specific programming language. Avoid duplicating a development kit for a language in which we already have a kit. Instead, you should propose changes to the existing development kit by submitting pull requests to our github repository. We'll make sure to review your pull request in a timely fashion.
  2. Avoid external dependencies. Try to make your kit as easy as possible to use it in different web frameworks and environments.
  3. Provide a way to build the package from sources.
  4. It is recommended to write tests that can be run over a mock repository to ensure that everything in the kit is working properly.

What an API client should do:

  • Fetch the API entry document for a given URL (usually https://{repository-name}.prismic.io/api) and an optional access_token. Using a URL here is important: it makes it possible for the client to connect to any instance of our API and allow us future changes in the URL naming if needed.
  • Parse the API entry document and expose its data to a data structure that is idiomatic to the given programming language. In particular, the following data must be available: the ref list accessible by the given access_token, the bookmarks list, the forms list, the OAuth endpoints.
  • Allow the developer to select a form by name, pass it parameters, and submit it. If not specified otherwise, be sure to use the "Everything" form and the Master ref by default.
  • Parse the result of the form submission and return it as a document list.
  • For a document, give access to individual fragments by name, and provide some helpers to manipulate and display the data contained in these fragments (such as asHtmlgetFirstImageasFormattedDate, etc.). For the helpers that are supposed to build URLs from document links (like StructuredText.asHtml, for instance), you will probably need to handle a user-built linkResolver (a function that will determine the url of a linked document).
  • Ideally, provide some kind of basic overridable caching system. It is best if it's based on our eternal cache approach for all calls but the /api endpoint, while minimizing dependency over third-party libraries (for instance, a LRU cache storing the cache items in memory, is ideal). Potentially, you can also add a cache that makes sure that the only remaining API call, which is the /api endpoint, is not called more than once every few seconds.

Basically, as a developer using your development kit, I must be able to:

  • Fetch the API for my prismic.io repository URL.
  • Select a form and fill it with a given ref, a set of predicates, and parameters such as lang or orderings (and potentially other ones if needed in the future).
  • Submit the form and access to the resulting documents list in an efficient way.
  • Extract the needed information from these documents to display them in my application.

The prismic.io query API is RESTFul

Because we have designed the query API to be RESTFul, your development kit must be compatible with the REST design. That means that the API is server-driven, and the server will construct all transition links in the API. In your codebase you must not hard-code or try to forge any URLs. The development kit must follow the links provided by the server.

It is important to respect this rule, so that your development kit won't break on any new feature we might add in the future.

Framework kits

A starter project is a real project that you can run and that will quickly display documents from a content repository. It can be used as a base for any real project and must demonstrate the basic features of any prismic.io application:

  • Provide a sensible way for the user to input its technical configuration in the code (endpoint's URL, OAuth credentials, linkResolver, etc.)
  • Connect to any existing prismic.io repository
  • Display a list of documents
  • Display a detailed version of a given document, fetched by its ID or UID
  • Implement content previewing
  • Implement the in-website edit button and Experiments

A prismic.io framework is written for a given development framework (be it a web framework or something else). It must respect the development guidelines promoted by that particular development framework.

You should add as many other dependencies that make working with this specific development framework and prismic.io fun & easy (such as template language, date formatting libraries, etc.).

Your prismic.io framework should provide a few helpers that make it easy to integrate with the development framework. Typically for most web frameworks we provide a helper that creates a prismic.io Context that follows the HTTP request lifecycle and allows you to share a single session for a given website request.

You can also provide additional helpers that make it more idiomatic to work with prismic.io and a given development framework (for instance, a function to call a single document from its ID, a function to call a single document from its bookmark name, etc.)

As a prismic.io framework can work with any prismic.io repository, it doesn't assume anything about the document types. That's why it usually uses the document's UID to present a document in a list, and displays a sequential list of all the document's fragments when asked to display a detailed version.

Finally, the prismic.io framework must already contain the OAuth logic that allows you to obtain a temporary access_token needed to preview the application in a future release.

Samples and Themes

Samples are real working websites allowing users to quickstart a new project based on a set of custom types and working code. This sample needs to follow the rules for a prismic.io framework or use an existing prismic.io framework.

Discover more about how to create a theme.