Tutorial: Creating and expanding access for a GraphQL endpoint inside of Brightspot

In this tutorial, you will create a restricted GraphQL endpoint inside of Brightspot, and then gradually expand its access. Though you will be working with a GraphQL delivery API endpoint, the principles outlined in this tutorial apply to management API endpoints as well. As part of the effort, you will complete the following steps:

1. Complete a prerequisite step of creating two articles, each owned by a different site.
2. Create a GraphQL endpoint that restricts access to only those clients with an API key.
3. Expand access to the endpoint, but maintain some restrictions on the site from which you can fetch articles.
4. Open access to the endpoint completely.
5. View analytics related to the endpoint.

Assumptions

This tutorial assumes the following:

• Familiarity with GraphQL
• Familiarity with Cross-Origin Resource Sharing (CORS)
• Familiarity with the editorial process of creating an article in Brightspot
• A Brightspot environment that includes more than one site

Step 1: Creating prerequisite articles in Brightspot

To begin, create two articles in Brightspot, each owned by a different site. These articles will be referenced in validation steps later in this tutorial.

Creating the first article in site A

1. In the header, click add.
2. From the Create list, select Article.
3. In the Headline field, enter GraphQL-related article 1.
4. Click Publish.
5. In your browser's URL field, copy the article's UUID from the URL query string (found after id= parameter), then save this value for later.

Navigating to site B and creating the second article

1. Click the site name in the right side of the header.
2. Select site B.
3. In the header, click add.
4. From the Create list, select Article.
5. In the Headline field, enter GraphQL-related article 2.
6. Click Publish.
7. In your browser's URL field, copy the article's UUID from the URL query string (found after id= parameter), then save this value for later.

You now have two articles that you will use in validation steps as you build and re-configure a GraphQL endpoint.

Step 2: Creating a basic GraphQL API endpoint that requires an API key

In this step, you will create a basic GraphQL endpoint that requires an API key.

As part of this effort, you will:

• Use the Brightspot user interface to create a new GraphQL API endpoint
• Familiarize yourself with the basics of creating an endpoint
• Configure schema settings
• Require an API key to access to the endpoint
• Query the endpoint and validate that it is working correctly using the Brightspot user interface

Accessing the Brightspot API user interface and creating a new endpoint

In this step, you will initiate the creation of a GraphQL delivery API endpoint in Brightspot.

1. Ensure you are logged into Brightspot.
2. Click menu > Admin > APIs.
3. In the left rail, from the Endpoints list and under the Create menu, select GraphQL Delivery API, then click New. See the image below.
   

   

Naming the endpoint and select its version

Now you will name the endpoint, after which Brightspot automatically generates a draft of the endpoint's path. Endpoint paths are tied to Brightspot's permalink system and associated with the Global site, which ensures that an endpoint's path is not a duplicate. If a duplicate exists upon trying to save the endpoint, Brightspot indicates this in an error message and prevents you from saving. The Path field is editable so that you may give it a unique value if needed.

1. In the Name field, enter Hello World as the name for the endpoint. This is an internal name used to reference the endpoint in the Endpoints list in the left rail.

2. In the Path field, verify that /graphql/delivery/hello-world is automatically generated from the Name field. Your edit page looks similar to the following image.

   

3. From the Version list, select 1. Depending on your version of Brightspot, this may be the only available option in the list and selected by default.

Configuring schema settings

In this step, you will configure the endpoint's schema settings.

1. From the Schema Settings list, select Recordable.
2. From the Query Entry Types list, select Article. By doing this, you are restricting the endpoint to only fetching articles, which for this tutorial is part of the requirements.
3. In the Default Query Limit and Max Query Limit fields, retain the default values (10 and 100, respectively).
4. Your edit page looks similar to the following image.

Restricting access to API key

Now, you will require an API key for a client to hit the endpoint. Though this step implies the existence of an API client, you will not create one until later in this tutorial.

1. From the Access list, select API Key Required.

2. Click Save.

   Note

   After saving the endpoint, the Paths field at the bottom of this edit form displays the same path as the one auto-generated from the Name field; the Paths field exists so that you know the endpoint path even when the endpoint is created programatically. For details, see Tutorial: Programmatically creating a GraphQL endpoint for an admin team.

Verifying that the endpoint is working via the Advanced tab

At this point, you must validate that the endpoint is working. You will do this by querying the endpoint, then checking the load result in the Advanced tab. On this tab, you see information about the schema load result, including its status, duration, and any exceptions. It also displays the schema version history.

1. Combining your back-end environment's domain with the endpoint path, query the endpoint in your browser.
2. Back on the endpoint edit page, in the top right of the screen, click more_horiz, then click Advanced.
3. Click Schema Load Result.
4. In the Status field, confirm that the status is Done.
5. In the Load Duration field, ensure the load time is acceptable.
6. In the Schema Load Exception field, check for any exceptions thrown by the endpoint and rectify as necessary.
   
   Note

   The Schema Load Exception field is dynamically generated, making it especially useful when, for example, creating a management API endpoint that includes two query entry types that share the same name. Information about dynamic disambiguation, including new names generated for them, appears in in this field.
7. Under Schema Versions, note the change log for each revision of the schema. To view more detailed information, click visibility.

You have now created a basic GraphQL Delivery API endpoint that requires an API key.

Step 3: Expanding access to the API endpoint

You now have created a GraphQL delivery API endpoint that requires an API key to fetch articles; however, in this step, you will expand the endpoint's access so that it no longer requires an API key to fetch articles, but is still restricted to fetching articles only from a specific site. You do this by adjusting the existing API client and assigning site permissions to it. The end result will be an API that can only fetch articles from a site of your choosing.

In this step, you will:

1. Create an API client in Brightspot and assign site permissions to it.
2. Change the endpoint's access and slot in the API client as the endpoint's attributional client.
3. Validate that the endpoint is configured correctly using the GraphQL explorer.

Creating new API client and assigning site permissions to it

Begin by initiating the creation process of an API client.

1. In the left rail, from the Clients list, click New API Client.

   

2. In the Name field, enter Example App.
3. Under Endpoints, click add_circle_outline, then select the Hello World endpoint.
   
   Note

   To see a list of clients associated with a given endpoint, refer to the Clients field at the bottom of the endpoint's edit page.
4. Under Permissions, click add_circle_outline, then do the following:
   
   1. Under Sites, click add_circle_outline to open a list of sites.
   2. Select the site to which you want to limit requests made from this API client. Your content edit form should look like the following image.
      

      

   3. Repeat steps 4a–4b to add additional sites as necessary.
   Note

   By default, only site permissions are available; however, permissions can be extended to other use cases as well.

5. Click Save.

Assigning the API client as the attributional client for your endpoint

1. In the left rail, from the Endpoints list, click Hello World.
2. Under the Access field, select Anyone.

3. From the Attributional Client list, select the API client you created, Example App.

   Note

   The Attributional Client field is an optional field that serves two purposes:
   

   • When retrieving analytics data about requests made to the endpoint, Brightspot attributes these requests to the attributional client in this field.
   • Permissions set to the attributional client in this field are applied to all requests made to this endpoint.

4. Click Save.

Verifying the API endpoint is working via GraphQL Explorer

At this point, you must validate that the site-restricted endpoint is working. You will do this by opening the GraphQL explorer and querying the endpoint, ensuring that it only returns articles from the site you specified for the API client.

1. In the top right of the screen, click more_horiz, then click GraphQL Explorer.
2. In the left panel, build the following query:
   
   1. Expand Article.
   2. Expand model:.
   3. Click id:.

   4. Enter the UUID of the first article you created in Step 1.

      query MyQuery {
        Article(model: {id: ""})
      }

      • Insert the UUID of the first article you created in step 1.

3. In the middle panel, execute the query:
   
   1. Click the execute button to run the query. Your result should look similar to the following code snippet.
      

      {
        "data": {
          "Article": {
            "subHeadline": null,
            "headline": "GraphQL-related article 1",
            "priority": null,
            "changeFrequency": null,
            "_id": ""
          }
        }
      }

      • The result returns the name of the first article you created in step 1 of this tutorial.
      • Contains the UUID of the first article you created in step 1 of this tutorial.
4. In the middle panel, make the following adjustments to the query, then execute the query again:
   
   1. In line 2, replace the UUID for the first article you created with the UUID of the second article you created.
   2. Execute the query. Your result looks similar to the following code snippet.
      

      {
        "data": {
          "Article": null
        }
      }

      • The result returns null, indicating that you are not able to query for an article created in a site to which the API client does not have permission.

You have now verified that the endpoint is configured correctly. Additionally, you have verified that the endpoint is restricted to only fetching articles from the site you specified in the API client's permissions.

Step 4: Opening access to the endpoint completely

Now, you will completely open up access to the endpoint.

As part of this effort, you will:

1. Open access to the endpoint
2. Validate that the endpoint is working correctly using the GraphQL explorer

Completely opening access to the endpoint

In this step, you will be opening access to the endpoint so that there are no restrictions of who can access it.

1. Click menu > Admin > APIs.
2. In the left rail, from the Endpoints list, select Hello World.
3. In the Attributional Client field, click close to remove Example App as the attributional client.
4. Toggle on Allow Introspection Queries.
   
   Note

   With a truly open-access API endpoint, you have the option of enabling introspection queries by toggling on Allow Introspection Queries. You can only enable introspection queries on production servers. If the server is not marked as a production server, this toggle has no effect.
   
   Brightspot recommends only toggling on this setting if your API is meant for public consumption.
5. Click Save.

Validating that access is completely open via the GraphQL Explorer

Now that you have opened access to the endpoint completely, you will verify that you configured it correctly. You will do this by using the GraphQL explorer to query for the second article you made in Step 1 of this tutorial.

1. In the top right of the screen, click more_horiz, then click GraphQL Explorer.
2. In the left panel, build the following query:
   
   1. Expand Article.
   2. Expand model:.
   3. Click id:.
   4. Enter the UUID of the first article you created in Step 1.
      

      query MyQuery {
        Article(model: {id: ""})
      }

      • Insert the UUID of the first article you created in step 1.
3. In the middle panel, execute the query:
   
   1. Click the execute button to run the query. Your result looks similar to the following code snippet.
      

      {
        "data": {
          "Article": {
            "subHeadline": null,
            "headline": "GraphQL-related article 1",
            "priority": null,
            "changeFrequency": null,
            "_id": ""
          }
        }
      }

      • The result returns the name of the first article you created in step 1 of this tutorial.
      • Contains the UUID of the first article you created in step 1 of this tutorial.
4. In the middle panel, make the following adjustments to the query, then execute the query again:
   
   1. In line 2, replace the UUID for the first article you created with the UUID of the second article you created.
   2. Execute the query. Your result looks similar to the following code snippet.
      

      {
        "data": {
          "Article": {
            "subHeadline": null,
            "headline": "GraphQL-related article 2",
            "priority": null,
            "changeFrequency": null,
            "_id": ""
          }
        }
      }

      • The result returns the name of the second article you created in step 1, indicating that the site restrictions are no longer in place.

You have now verified that the endpoint is configured correctly. Additionally, you have verified that the endpoint has no restrictions.

Step 5: Checking endpoint analytics

Now that you have created and queried a GraphQL delivery API endpoint, you can view its analytics.

Checking endpoint analytics via the Analytics tab

Once requests are made against the endpoint, you will verify that it is working correctly via the Analytics tab. On this tab, you can view data about the requests, including a subset of data exclusive to the client Example App that you configured as a result of this tutorial.

1. Click menu > Admin > APIs.
2. In the left rail, from the Endpoints list, select the Hello World endpoint you created.
3. In the top right of the screen, click more_horiz, then click Analytics.
4. In the Clients field, view a client-specific breakdown of when the endpoint was last accessed by the client Example App, as well as how many requests this client made.
5. In the Last Accessed field, note the last time a request was made against the endpoint.
   
   Note

   The time displayed in this field is always set to be in five-minute increments. The final digit always ends in either 0 or 5.

6. In the Request Count field, you can see the number of requests made against the endpoint overall. The image below is an example of what this tab may look like for you.

   

You have now viewed analytics on the endpoint you created as a result of this tutorial.