Getting Started with JSON API and REST

Goal

Install and configure Drupal using best practices to act as the backend for a decoupled website.

Questions the guide should answer

Should we cover blocks? And using blocks in a decoupled site?
Menus
Routing, and redirects

Outline

1. Install Drupal
2. Setup your content architecture - considerations for decoupled sites
   1. For example; how does using paragraphs impact things for a decoupled site?
3. Enable and configure JSON:API
4. Drupal core Rest module - when to use it?
5. JSON:API Extras
6. Set up a menu to be consumed by the frontend application
7. Make sure users can register an account via the API
8. Setting up CORS
9. Setting up a view to provide REST API endpoints
10. Setting up site specific API documentation
11. Optimize Drupal for a “headless” content management experience
12. Configure Drupal to allow the frontend application to create comments
13. Make Drupal an authentication provider (e.g. OAuth2)
14. Deploy your Drupal site
15. List of frequently used contributed modules with brief explanation of each

Things we could maybe cover as add-on material later:

• Layout Builder
• Views
• Blocks

Ref: https://www.drupal.org/project/project_module?f%5B2%5D=im_vid_3%3A186018

3. Install and Configure the JSON:API module

Most decoupled Drupal applications will use the Drupal core JSON:API module to expose a RESTful API that implements the JSON:API spec. The core JSON:API module serves as a wrapper around Drupal's content modelling (entities and fields) and provides a way for 3rd party code to access a Drupal sites content and features.

By adhering to the JSON:API spec the API your application exposes will be compatible with all the tooling in the JSON:API ecosystem. And allows for the creation of generalized libraries, and other helpers that can abstract away some of the need to understand Drupal's internals.

You can learn more about installing the JSON:API module, and making API requests to retrieve, create, update, and delete content in the JSON:API module guide.

4. The Drupal core REST module

Drupal's JSON:API implementation is closely coupled to the entity system and can only operate on entities. If you need to gain access to any non-entity data you'll need to use the core REST module. Additionally while the JSON:API module uses JSON for all it's requests and responses, the core REST module can use any format (XML, Soap, etc.). The REST module is extremely configurable and allows for anything (any request/response format, any business logic, any HTTP methods) but requires a considerable amount of set up to use.

For a full comparison see JSON:API versus Core's REST Module.

Another thing to consider is that the JSON:API module does not support the execution of business logic like registering a new user account, or resetting the password of an existing account. Operations that are not specific to content CRUD and where a request might trigger more complex logic that may or may not result in the creation or updating of any entity.

8. Setting up CORS

Cross-Origin Resource Sharing (CORS)open in new window in MDN Web Docs explains the concept very well. In case the frontend application is served from a different domain, then we need to make sure the "Cross origin resource sharing" is enabled and configured properly.

As of Drupal 8.2, it's possible to opt in a particular site to enable CORS for responses served by Drupal. This is not enabled by default because there are security consequences.

Following configuration can be found inside default.services.yml shipped along with Drupal.

# Configure Cross-Site HTTP requests (CORS).
  # Read https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
  # for more information about the topic in general.
  # Note: By default the configuration is disabled.
 cors.config:
   enabled: false
   # Specify allowed headers, like 'x-allowed-header'.
   allowedHeaders: []
   # Specify allowed request methods, specify ['*'] to allow all possible ones.
   allowedMethods: []
   # Configure requests allowed from specific origins.
   allowedOrigins: ['*']
   # Sets the Access-Control-Expose-Headers header.
   exposedHeaders: false
   # Sets the Access-Control-Max-Age header.
   maxAge: false
   # Sets the Access-Control-Allow-Credentials header.
   supportsCredentials: false

Please pay attention to enabled: false key-value pair! Changing the value to enabled: true would allow CORS request.

9. Setting up a view to provide REST API endpoints

Log in as an admin on the Drupal site, then go to Structure > Views, then click on the "Add view" button. On the next screen, the View name can be any name desired, however a simple name of "REST View" can work here, which will generate a machine name of "rest_view". Most of the settings on this screen can remain blank as default, with the exception of "Provide a REST export" under REST export settings, which should be checked. After this checkbox is checked, any path desired can be entered here. A simple path of "/api/content" can work here for the purpose of getting content nodes. Finally, click "Save and edit" to add the view.

On the next screen which shows the view properties, expand the Advanced section if needed, then the Add button next to "Contextual filters". Inside the pop-up modal, search for "ID" to find "ID | Content" (Title | Category) in the list, and then click "Add and configure contextual filters". Alternatively, "Has taxonomy term ID | Content" can be used to get content by its associated taxonomy term ID. A module Views taxonomy term name into ID is also available to use the taxonomy term itself, rather than the ID. On the next screen inside the modal, click Apply to finish (the options can all be left as default) and close the modal. Back on the view properties screen, click Save to save all changes.