Customizing field arguments in Brightspot Content Delivery API

There exist use cases where the default id and path arguments exposed in a Content Delivery API (CDA) do not fit the intended functionality. Fortunately, they are flexible!

Prerequisites

For endpoint configuration: Custom Content Delivery API development or Hello Content Delivery API.

Introduction

When exposing GraphQL APIs via Brightspot’s view system, data is typically queried for by ID or path. However, there are cases in which callers may want to query by some other criteria, like a third-party ID or maybe even remove the arguments altogether, leaving object resolution up to the view model.

Background

When it comes to removing the arguments completely, we can accomplish this by using the correct generic argument for the relevant ViewModel class. There are two ways to go about this:

Leverage Brightspot’s Singleton interface on your view model’s model.
Utilize your ContentDeliveryApiEndpoint subclass as your view model’s model.

For adding custom arguments we can leverage Brightspot’s @WebParameter annotation. It allows us to treat scalar fields, such as integers, strings, and even lists of them, as an argument.Additionally, we can create custom Java annotations that are utilized to denote a field that should be transformed into an argument with a custom input type, and even populate a Java POJO, by using ContentDeliveryApiWebAnnotationProcessor.

Examples

View model with singleton model

showLineNumbers

1public class Homepage extends Content implements Singleton {
2
3    private String title;
4
5    public String getTitle() {
6        return title;
7    }
8
9    public void setTitle(String title) {
10        this.title = title;
11    }
12}
13
14@ViewInterface
15public class HomePageViewModel extends ViewModel<Homepage> {
16
17    public String getTitle() {
18        return model.getTitle();
19    }
20}

The following types are generated in the resulting schema:

showLineNumbers

1type Query {
2    Homepage: Homepage
3}
4
5type Homepage {
6    title: String
7}

Callers are now able to query for the homepage without any arguments since the system knows how to find the one and only.

API entry field

Sometimes API designers may not need to use a data model, or may want to implement their own logic to resolve the proper data model. In this case, they can just use their endpoint class as the model for the view model.

Also, as discussed earlier, they can leverage @WebParameter to expose their own scalar arguments.

Consider the following classes:

showLineNumbers

1public class Article extends Content {
2
3    private String headline;
4
5    public String getHeadline() {
6        return headline;
7    }
8
9    public void setHeadline(String headline) {
10        this.headline = headline;
11    }
12}
13
14@ViewInterface
15public class ArticleViewModel extends ViewModel<Article> {
16
17    public String getHeadline() {
18        return model.getHeadline();
19    }
20}
21
22@ViewInterface
23public class ArticleSearchViewModel extends ViewModel<ArticleEndpoint> {
24
25    @WebParameter
26    private String search;
27
28    @WebParameter
29    private Integer limit = 5;
30
31    public Iterable<ArticleViewModel> getArticles() {
32        Query<Article> articleQuery = Query.from(Article.class);
33
34        if (!StringUtils.isBlank(search)) {
35            articleQuery.where("* matches ?", search);
36        }
37
38        final int maxLimit = 50;
39
40        return createViews(ArticleViewModel.class, articleQuery
41            .select(0, Math.min(limit, maxLimit)).getItems());
42    }
43}
44
45public class ArticleEndpoint extends ContentDeliveryApiEndpoint {
46
47    @Override
48    protected String getPathSuffix() {
49        return "/article";
50    }
51
52    @Override
53    public List<ContentDeliveryEntryPointField> getQueryEntryFields() {
54        return Collections.singletonList(new ContentDeliveryEntryPointField(ArticleSearchViewModel.class));
55    }
56}

The following types are generated in the resulting schema:

showLineNumbers

1type Query {
2    ArticleSearch(search: String, limit: Int): ArticleSearch
3}
4
5type ArticleSearch {
6    articles: [Article]
7}
8
9type Article {
10    headline: String
11}

The @WebParameter annotated fields are assigned to their respective argument value passed in the GraphQL query, and are utilized in the view model logic. Callers are now able to query for articles via a general full-text search.

Custom input type

API designers may want to expose a structured input type and have it populate some custom type on the back end. This is easily achievable with a custom Java annotation and a ContentDeliveryApiWebAnntoationProcessor implementation.

Consider the following classes:

showLineNumbers

1public class Person {
2
3    private String name;
4
5    private String location;
6
7    public String getName() {
8        return name;
9    }
10
11    public void setName(String name) {
12        this.name = name;
13    }
14
15    public String getLocation() {
16        return location;
17    }
18
19    public void setLocation(String location) {
20        this.location = location;
21    }
22}
23
24@Documented
25@Retention(RetentionPolicy.RUNTIME)
26@Target(ElementType.FIELD)
27public @interface CurrentPerson {
28
29}
30
31public class CurrentPersonProcessor implements ContentDeliveryApiWebAnnotationProcessor<CurrentPerson> {
32
33    @Override
34    public Object getValue(ApiRequest request, Object input, Field field, CurrentPerson annotation) {
35        String name = (String) CollectionUtils.getByPath(input, "name");
36        String location = (String) CollectionUtils.getByPath(input, "location");
37
38        Person person = new Person();
39        person.setName(name);
40        person.setLocation(location);
41
42        return person;
43    }
44
45    @Override
46    public SchemaInputType getInputType(Field field, CurrentPerson annotation) {
47        return SchemaInputTypes.newInputObject("Person")
48            .field("name", SchemaInputTypes.nonNullOf(SchemaInputTypes.STRING))
49            .field("location", SchemaInputTypes.nonNullOf(SchemaInputTypes.STRING))
50            .build();
51    }
52}
53
54public class GreetingEndpoint extends ContentDeliveryApiEndpoint {
55
56    @Override
57    protected String getPathSuffix() {
58        return "/greeting";
59    }
60
61    @Override
62    public List<ContentDeliveryEntryPointField> getQueryEntryFields() {
63        return Collections.singletonList(new ContentDeliveryEntryPointField(GreetingViewModel.class));
64    }
65}
66
67@ViewInterface
68public class GreetingViewModel extends ViewModel<GreetingEndpoint> {
69
70    @CurrentPerson
71    private Person person;
72
73    public String getGreeting() {
74        return "Hello " + person.getName() + " from " + person.getLocation() + "!";
75    }
76}

The following types are generated in the resulting schema:

showLineNumbers

1type Query {
2    Greeting(person: Person): Greeting
3}
4
5type Greeting {
6    greeting: String
7}
8
9input Person {
10    name: String!
11    location: String!
12}

The @CurrentPerson annotated field is assigned to its respective argument value passed in the GraphQL query, and is utilized in the view model logic.