Core Concepts

• Servers
• Resources
  • Schemas
  • API Resources
• Requests

Servers

Your Laravel application can have any number of JSON:API compliant APIs. We refer to each API as a Server.

You may not use multiple servers: a simple application may only have one server. However, there are a number of use cases where you may decide to implement multiple servers. For example:

• If you have a public-facing API, and a private API (e.g. only accessible by administrators).
• If you want to maintain multiple versions of an API, each version can have its own server.

Resources

Every server has a defined set of JSON:API resources. These are the domain models that clients can access via your API.

For example, a blog application may have posts, comments and users resources to represent the blog posts, comments on those posts, and the users who have authored posts or comments.

Schemas

For each resource in your server, you will have a Schema class. For example, the posts resource would have a PostSchema class.

The PostSchema describes the structure of the posts resource and translates JSON:API requests into database queries to create, read, update and delete Post models.

The design of Schema classes is inspired by the Laravel Nova (opens new window) approach.

API Resources

By default, we use the PostSchema to serialize a Post model to a JSON:API resource object.

If you need full control over the serialization of a model to JSON, you can use a Resource class to define the JSON structure.

For example, your posts resource could have a PostResource class defining the serialization. These resource classes are the JSON:API equivalent of Laravel's Eloquent API Resources (opens new window).

Requests

Laravel JSON:API makes extensive use of Laravel Form Requests (opens new window) to process client requests in accordance with the JSON:API specification.

Our request classes take care of:

• Negotiating content (opens new window) between the client and the server;
• Parsing JSON documents sent by client against the JSON:API specification, rejecting any non-compliant documents with detailed error messages.
• Validating query parameters and JSON resources against your application's specific validation logic.

A resource can have up to three request classes. Using the posts resource as an example, the three classes would be:

• PostRequest: parses the JSON content of a request to create, update, or delete a posts resource. This includes parsing requests to modify any of the relationships of the posts resource.
• PostQuery: parses query parameters for when the server will respond with zero-to-one posts resources.
• PostCollectionQuery: parses query parameters for when the server will respond with zero-to-many posts resources.

TIP

Not all resources will use all three request classes: it depends on what JSON:API capabilities you allow a client to execute for each resource type.