Skip to main content

Tutorial: Programmatically creating a GraphQL endpoint for an admin team

In this tutorial, you will programmatically create a GraphQL endpoint so that an administrator can manage it later in Brightspot. The endpoint requirements are as follows:

  • The endpoint should be able to fetch data from a content type that you define.
  • When the endpoint is deployed, it should be immediately available to the administrator.
  • The administrator should be able to control whether or not an API key is required.
  • The administrator should be able to control whether or not introspective queries are allowed in certain environments.

Because your admin team includes individuals of varying technical expertise, you will limit the number of configurable fields to only the two listed above—Access Option and Allow Introspection Queries—helping prevent mis-configuration of the endpoint. For a look into the administrator's role in this process, see Tutorial: Creating and expanding access for an endpoint in Brightspot.

In this tutorial, you will:

  1. Create a data model and view model.
  2. Create a Java class that will contain the endpoint configuration.
  3. Add a URL path from which the endpoint can be accessed.
  4. Configure the endpoint to fetch data from the data model.
  5. Allow an administrator to control whether or not an API key is required.
  6. Allow an administrator to control whether or not to allow introspective queries.

Assumptions​

This tutorial assumes the following:

  • Familiarity with Brightspot's Java APIs
  • Familiarity with GraphQL

Step 1: Create a data model and view model​

As a prerequisite for this tutorial, you will create two Java classes for your data model and view model, respectively.

For the data model, you will create a Java class named Product that extends Content.

showLineNumbers
1
public class Product extends Content {

2


3
    private String name;

4


5
    private String description;

6


7
    private String color;

8


9
    public String getName() {

10
        return name;

11
    }

12


13
    public String getDescription() {

14
        return description;

15
    }

16


17
    public String getColor() {

18
        return color;

19
    }

20
}

For the view model, you will create a Java class named ProductViewModel that extends ViewModel<Product>.

showLineNumbers
1
@ViewInterface

2
public class ProductViewModel extends ViewModel<Product> {

3


4
    public String getColor() {

5
        return model.getColor();

6
    }

7


8
    public String getName() {

9
        return model.getName();

10
    }

11


12
    public String getMessage() {

13
        return String.format("%s: %s: %s", getName(), getColor(), model.getDescription());

14
    }

15
}

Step 2: Create a Java class that will contain the endpoint configuration​

In this step, you will be creating a single instance of a Java class named ProductDeliveryEndpoint that extends ContentDeliveryApiEndpoint. Because you will implement Singleton, the endpoint will be immediately available to the administrator when you deploy the code.

Note

This tutorial outlines the creation of a delivery API endpoint. For more information on management API endpoints, see Hello Content Management API.

showLineNumbers
1
@DisplayName("Product Delivery API")

2
public class ProductDeliveryEndpoint extends ContentDeliveryApiEndpoint implements Singleton {

Step 3: Add a URL path from which the endpoint can be accessed​

In this step, you will specify a URL path with which to hit the endpoint. Endpoint URL paths are tied to Brightspot's permalink system, which automatically validates a given URL path for uniqueness.

showLineNumbers {2}
1
@Override

2
public Set<String> getPaths() {

3
    return Collections.singleton("/product-delivery-api");

4
}
  • 2. This API allows you to specify multiple URL paths from which the endpoint can be accessed; however, for the purposes of this tutorial, you will create only one.
Note

To hit the endpoint, append the URL path above onto the domain of your Brightspot instance (for example: https://cms.example.com/product-delivery-api-endpoint).

Step 4: Configuring the endpoint to fetch data from the data model​

In this step, you will configure the endpoint so that it can fetch data. You will do this by creating a query entry field—a top-level field on the Query type—for use with your endpoint.

showLineNumbers {4}
1
@Override

2
    public List<ContentDeliveryEntryPointField> getQueryEntryFields() {

3
        return Collections.singletonList(

4
            new ContentDeliveryEntryPointField(ProductViewModel.class));

5
    }
  • 4. References the view model you created in step 2 of this tutorial.

Step 5: Allow an administrator to control whether or not an API key is required​

In this step, you will make the endpoint's access level configurable for an administrator. Over the course of the exercise, you will expand the code to control the future use of the field and prevent a validation error from occurring upon save.

  1. Define the editorial field.

    showLineNumbers
    1
    @Embedded

    2
    private GraphQLApiAccessOption accessOption;

  2. Override the getApiAccessOption method, returning the editorially-specified value of the newly added field.

    showLineNumbers
    1
    @Override

    2
    public GraphQLApiAccessOption getApiAccessOption() {

    3
        return accessOption;

    4
    }

  3. Make the field required.

    We add the @Required annotation here which has the effect of an error message displaying in the Brightspot UI if a user attempts to submit the form with a blank value for the field.

    showLineNumbers
    1
    @Embedded

    2
    @Required

    3
    private GraphQLApiAccessOption accessOption;

  4. Prevent a validation exception on save.

    Because it is a Singleton, Brightspot will attempt to save the instance of the endpoint the first time you deploy the code. Since the Access Option field has no value yet, the save would fail with a validation error (because of the aforementioned @Required annotation). The following beforeSave() implementation mitigates this problem by defaulting the value to an option that requires an API key.

    showLineNumbers
    1
    @Override

    2
    protected void beforeSave() {

    3
        super.beforeSave();

    4
    

    5
        if (accessOption == null) {

    6
            accessOption = new GraphQLApiAccessOptionExplicit();

    7
        }

    8
    }

Your code should now look similar to the following:

showLineNumbers
1
@Embedded

2
@Required

3
private GraphQLApiAccessOption accessOption;

4


5
@Override

6
public GraphQLApiAccessOption getApiAccessOption() {

7
    return accessOption;

8
}

9


10
@Override

11
protected void beforeSave() {

12
    super.beforeSave();

13


14
    if (accessOption == null) {

15
        accessOption = new GraphQLApiAccessOptionExplicit();

16
    }

17
}

Step 6: Allow an administrator to control whether or not to allow introspective queries​

For the purposes of this tutorial, the company that gave you these endpoint requirements has three environments: QA, UAT, and Production. An administrator may want to configure whether introspection queries are allowed on a per-environment basis; to facilitate that, in this step you will add a Allow Introspection Queries toggle field to Brightspot.

showLineNumbers
1
private Boolean allowIntrospectionQueries;

2


3
@Override

4
public IntrospectionQueryRule getIntrospectionQueryRule() {

5
    return () -> Boolean.TRUE.equals(allowIntrospectionQueries);

6
}

Result​

All together, your data model, view model, and endpoint now resemble the following code snippets:

Product.java​

showLineNumbers
1
public class Product extends Content {

2


3
    private String name;

4


5
    private String description;

6


7
    private String color;

8


9
    public String getName() {

10
        return name;

11
    }

12


13
    public String getDescription() {

14
        return description;

15
    }

16


17
    public String getColor() {

18
        return color;

19
    }

20
}

ProductViewModel.java​

showLineNumbers
1
@ViewInterface

2
public class ProductViewModel extends ViewModel<Product> {

3


4
    public String getColor() {

5
        return model.getColor();

6
    }

7


8
    public String getName() {

9
        return model.getName();

10
    }

11


12
    public String getMessage() {

13
        return String.format("%s: %s: %s", getName(), getColor(), model.getDescription());

14
    }

15
}

ProductDeliveryEndpoint.java​

showLineNumbers
1
@Recordable.DisplayName("Product Delivery API")

2
public class ProductDeliveryEndpoint extends ContentDeliveryApiEndpoint implements Singleton {

3


4
    @Embedded

5
    @Required

6
    private GraphQLApiAccessOption accessOption;

7


8
    private Boolean allowIntrospectionQueries;

9


10
    @Override

11
    public List<ContentDeliveryEntryPointField> getQueryEntryFields() {

12
        return Collections.singletonList(

13
            new ContentDeliveryEntryPointField(ProductViewModel.class));

14
    }

15


16
    @Override

17
    public Set<String> getPaths() {

18
        return Collections.singleton("/product-delivery-api");

19
    }

20


21
    @Override

22
    public GraphQLApiAccessOption getApiAccessOption() {

23
        return accessOption;

24
    }

25


26
    @Override

27
    public IntrospectionQueryRule getIntrospectionQueryRule() {

28
        return () -> Boolean.TRUE.equals(allowIntrospectionQueries);

29
    }

30


31
    @Override

32
    protected void beforeSave() {

33
        super.beforeSave();

34


35
        if (accessOption == null) {

36
            accessOption = new GraphQLApiAccessOptionExplicit();

37
        }

38
    }

39
}
Note

After adding the following method and deploying the code, it will be the responsibility of the administrator to generate the API key and associate it with the endpoint. For a look into an administrator's role, see Tutorial: Creating and expanding access for an endpoint in Brightspot.