CDA vs. CMA: Which one should we use?
Brightspot offers two main APIs for generating GraphQL endpoints:
ContentDeliveryApiEndpoint (CDA) and
ContentManagementApiEndpoint (CMA). There is overlap in functionality between these two solutions, which can make it unclear as to what the right choice is. It is important to consider the names of the two APIs when evaluating them against a use case. CDAs are focused on delivering data to some downstream user, many times, via a frontend like a web browser or native application. CMAs are focused on managing CMS data and support much more internal business use cases like automated testing, data ingestions and exports, and powering custom CMS user interfaces. Although the distinction between “delivery” and “management” seems to imply that the former is for only for reading, they both have the ability to expose CRUD operations for Brightspot data, so data manipulation should not be the only factor taken into consideration.
Content Delivery API
CDAs focus on exposing only what is necessary to power a specific experience. They expose mostly high-level Brightspot features, providing simple GraphQL APIs that are intuitive to implement.
CDAs can leverage Brightspot’s view system to provide a transformation layer for data before it is presented to the end user. This is very important for situations in which raw data from the database may need to stripped of internal information or transformed into a specific format. Conversely, the transformation layer is also great for cleaning and saving UGC (user-generated content) data input via the mutation GraphQL APIs that the CDA can expose. Additionally, developers have immense freedom in designing and customizing CDA APIs to reflect very specific intended schemas.
Sometimes the transformation layer is not necessary, and an API designer may want to pass modeled data straight through. CDAs can be configured with Brightspot types to take that extra step out of the process.
Content Management API
CMAs focus on exposing Brightspot concepts and APIs via GraphQL. This allows a caller to replicate much of the functionality available, through Java code, directly with the generated APIs. The extra functionality makes CMAs have a heavier footprint than a typical CDA and also far less customizable; however, callers have the ability to read and mutate most Brightspot data with only a simple endpoint configuration necessary on the backend.
How to create an API Client, furnish an API Key, set their permissions, and how to make requests on their behalf.
When creating a GraphQL endpoint, you may wish to restrict who has access to submit queries. With Brightspot’s GraphQL authentication features, you can control which clients have access to an endpoint, as well as what sites each client can retrieve content from.
Creating an API client
An API Client object represents an entity that has access to Brightspot’s GraphQL endpoints. The fields on the client object will determine what Sites it has access to, what endpoints it can query, and what API Keys it is associated with. To create an API Client, navigate to Admin > APIs in Brightspot and click New API Client on the left menu.
Under the Endpoints section, you can enumerate what GraphQL endpoints this client can access. For endpoints that are configured to require API Key access, your client will also need to have an API Key associated with it in order to retrieve content from the endpoint.
For detailed information about Sites Permissions, see Sites permissions.
Developers may also create their own custom permissions by extending the
ApiPermission class and implementing the
hasPermission method. Note that in order for a client to access data from an endpoint, the request must satisfy all permissions associated with the client.After configuring your API Client’s permissions, click Save. Your client is now ready to make requests to your endpoint.
GraphQL endpoints can be configured to require an API Key for access. For external applications to access such a GraphQL endpoint, they must use a client’s API Key. This key is a unique identifier that verifies the authenticity of the entity making the request and applies the corresponding permissions.
Furnishing an API key
To generate an API Key for a client, click the name of the desired client from the left menu of the APIs Dashboard. Under the Keys section, click Add API Key and an API key for this client will be generated. Click the clipboard icon to copy the API key to your clipboard; it will not be available once you leave this page. Click Save once you have copied the key.
Making requests from a client
When making requests with an API Key, the X-API-Key header should be included on the request. The value of this header will be the key generated in the previous section. If the X-API-Key header is not included in the request, Brightspot will attempt to retrieve the apiKey query string parameter from the request URL. If no API Key can be resolved, the request will not execute and an error will be returned.