Configuring JSON:API Features

Varbase 11.0.x provides a fully configured JSON:API interface through the Varbase API Base recipe. This enables headless and decoupled front-end architectures by exposing Drupal content and configuration as JSON:API endpoints, complete with authentication, authorization, and interactive API documentation.

Overview

The Varbase API Base recipe installs and configures the following components:

• JSON:API: Drupal's built-in JSON:API implementation for exposing entities as RESTful API endpoints.

• JSON:API Extras: Extends JSON:API with resource configuration, field aliasing, and the ability to enable or disable specific resources.

• Simple OAuth (OAuth2): Provides OAuth 2.0 authentication for API consumers, including support for client credentials, authorization code, and password grant types.

• OpenAPI: Generates API documentation following the OpenAPI (Swagger) specification.

• OpenAPI UI: Provides an interactive Swagger UI for browsing and testing API endpoints.

JSON:API Configuration

Accessing JSON:API Settings

JSON:API settings are managed through the JSON:API Extras module. Navigate to Configuration > Web services > JSON:API > Extras, or go to:

/admin/config/services/jsonapi/extras

Enabling and Disabling Resources

By default, JSON:API exposes all entity types as API resources. You can control which resources are available:

1. Navigate to Configuration > Web services > JSON:API > Resource overrides, or go to:

/admin/config/services/jsonapi/resource_types

1. Review the list of available resources.

2. Click on a resource to configure it:

   • Disable the resource entirely to prevent it from being exposed via the API.

   • Rename the resource type or individual fields for cleaner API naming.

   • Disable individual fields within a resource to control which data is exposed.

3. Save the configuration.

JSON:API Endpoints

JSON:API endpoints follow the pattern:

/jsonapi/{entity_type}/{bundle}

For example:

Endpoint	Description
/jsonapi/node/article	List all article nodes
/jsonapi/node/article/{uuid}	Get a specific article by UUID
/jsonapi/media/image	List all image media entities
/jsonapi/taxonomy_term/tags	List all tag taxonomy terms

Configuring Simple OAuth

Simple OAuth provides OAuth 2.0 authentication for API consumers. This is essential for protecting write operations and securing access to restricted content.

Creating an OAuth Consumer

1. Navigate to Configuration > People > Simple OAuth, or go to:

/admin/config/people/simple_oauth

1. Generate or upload the public and private keys required for OAuth token signing.

2. Navigate to People > OAuth Consumers, or go to:

/admin/config/services/consumer

1. Click Add consumer.

2. Configure the consumer:

   • Label: A descriptive name for the API consumer (for example, "Mobile App", "React Frontend").

   • Client ID: A unique identifier (auto-generated or custom).

   • New Secret: A secret key for client authentication.

   • Scopes/Roles: Assign Drupal roles that determine the permissions granted to this consumer.

   • Redirect URI: The callback URL for authorization code grants.

3. Save the consumer.

Obtaining an Access Token

API consumers obtain access tokens by making a POST request to the token endpoint:

curl -X POST /oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

The response includes an access token that should be included in subsequent API requests:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  /jsonapi/node/article

API Documentation with OpenAPI

Varbase API Base configures OpenAPI and Swagger UI to provide interactive API documentation.

Accessing the API Documentation

Navigate to Configuration > Web services > OpenAPI, or go to:

/admin/config/services/openapi

The Swagger UI provides:

• A complete list of all available API endpoints.

• Request and response schemas for each endpoint.

• An interactive "Try it out" feature for testing API calls directly from the browser.

• Authentication support for testing protected endpoints.

OpenAPI Documentation URL

The generated OpenAPI specification is available at:

/openapi/jsonapi

This specification can be imported into API development tools such as Postman, Insomnia, or code generation tools.

Best Practices

Security

• Always use HTTPS for API communication.

• Use OAuth 2.0 authentication for any write operations or access to restricted content.

• Disable JSON:API resources that do not need to be exposed.

• Review field-level access to ensure sensitive data is not inadvertently exposed.

Performance

• Use JSON:API's built-in sparse fieldsets (fields[node--article]=title,body) to request only the fields you need.

• Use include parameters (include=field_image,field_tags) to reduce the number of API requests by side-loading related resources.

• Enable Drupal's page cache and consider using a CDN for caching API responses.

CORS Configuration

If your front-end application runs on a different domain, you need to configure Cross-Origin Resource Sharing (CORS) in your Drupal services.yml file:

cors.config:
  enabled: true
  allowedHeaders: ['Content-Type', 'Authorization']
  allowedMethods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS']
  allowedOrigins: ['https://your-frontend-domain.com']
  maxAge: 3600