Support and Documentation

The Content Management API gives clients access to their Dari data models backed by the Java classes that define them. The API provides the same CRUD operations available when using the Dari Java APIs directly.

The API lives at the path /management/graphql and is only accessible on the Brightspot domain. This is the URL specified in Admin > Sites & Settings > Global > Default Tool URL. So, if that value is set to https://cms.example.com, then you can access this API by sending requests to https://cms.example.com/management/graphql. An Authentication key is required to access this endpoint, and that key may also have Site restrictions on it. If Site restrictions are present, then you must pass the ID of the Site with the request. It can either be passed as a query parameter in the URL named site or as a Header with the name X-BSP-SITE. If no restrictions exist, then you can freely access any content in the system.

Consider the content type defined by the following Java class:

package com.example;

import com.psddev.cms.db.Content;

public class Article extends Content {

    @Indexed
    private String title;

    public String getTitle() {
       return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }
}

Using the Dari Java APIs, you could create, update, read, and delete an Article with the following code:

public class Code {
    public static Object main() {
        // Create
        Article a = new Article();
        a.setTitle("GraphQL");
        a.save();

        // Read
        a = Query.from(Article.class)
            .where("title = ?", "GraphQL")
            .first();

        // Update
        a.setTitle("Brightspot");
        a.save();

        // Delete
        a.delete();

        return a.getTitle();
    }
}

With the GraphQL API, all the CRUD operations above are strictly typed. This means that for each content type, there is a unique set of query and mutation fields that are used to manage that type. Using the Article example above, here is a snippet from the generated schema representing the APIs available to you for this type.

 type Query {
   Article(id: ID, path: String): Article
   ArticleQuery(predicate: String, sorts: [Sort!], offset: Int, limit: Int): ArticleQueryResult
 }

 type Mutation {
   ArticleSave(object: ArticleInput): Article
   ArticleDelete(id: ID): Article
}

There are four operations that can be done for this type: two for reads and two for writes.

The Article and ArticleQuery fields are used to find content of that type. The Article field lets you look up a single Article content by its ID or permalink. The ArticleQuery field lets you search for multiple articles optionally supplying a predicate (see Predicates) to filter the results. While technically ArticleQuery can also be used to look up content by its ID, Article is for convenience since it is a common operation.

Much like in the Dari Java API Record#save, there is a single mutation field to handle both the create and update operations. You can use ArticleSave to create a new Article by omitting the id field from the input type ArticleInput. To update an existing Article, you must supply that Article's ID along with any other fields you wish to update.

And finally, the ArticleDelete mutation field can be used to delete an Article by passing its ID as the argument.

Based on this schema, we can replicate the logic from the Java snippet above.