Neomerx JSON API

https://github.com/neomerx/json-api
Admin
Neomerx JSON API is a framework-agnostic PHP package that fully implements the JSON API...
Tokens:93,345
Snippets:699
Trust Score:5.9
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/neomerx/json-api/wiki/Home

Use this command to install the neomerx/json-api package via Composer.

```bash
$ composer require neomerx/json-api
```

--------------------------------

### Install dependencies with Composer

Source: https://github.com/neomerx/json-api/blob/master/sample/README.md

Installs the project dependencies via Composer.

```bash
$ composer install
```

--------------------------------

### GET /articles/1?include=comments

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example request to include related comments with an article using the include parameter.

```http
GET /articles/1?include=comments HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### GET to-one relationship link response

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example response for a GET request to a to-one relationship link URL, showing the relationship data for an author.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/author",
    "related": "/articles/1/author"
  },
  "data": {
    "type": "people",
    "id": "12"
  }
}
```

--------------------------------

### GET /articles/1?include=comments.author

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example request to include nested related resources using a dot-separated path in the include parameter.

```http
GET /articles/1?include=comments.author HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### 404 Not Found response

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example response when a relationship link URL does not exist, e.g., when the parent resource does not exist.

```http
404 Not Found
```

--------------------------------

### GET /articles/1/relationships/comments?include=comments.author

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example request to fetch related resources from a relationship endpoint using the include parameter.

```http
GET /articles/1/relationships/comments?include=comments.author HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### GET to-many relationship link response

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example response for a GET request to a to-many relationship link URL, showing an array of resource identifier objects for tags.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/tags",
    "related": "/articles/1/tags"
  },
  "data": [
    { "type": "tags", "id": "2" },
    { "type": "tags", "id": "3" }
  ]
}
```

--------------------------------

### Query parameter family example

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Shows a URL with two distinct query parameters, page[offset] and page[limit], which belong to the same query parameter family.

```text
/?page[offset]=0&page[limit]=10
```

--------------------------------

### GET empty to-one relationship link response

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example response for a GET request to a to-one relationship link URL when the relationship is empty, returning data: null.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/author",
    "related": "/articles/1/author"
  },
  "data": null
}
```

--------------------------------

### Fetching Resources with GET Requests

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

HTTP requests to fetch a collection of articles, a single article, and an article's author. Each request uses the Accept header application/vnd.api+json.

```http
GET /articles HTTP/1.1
Accept: application/vnd.api+json
```

```http
GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json
```

```http
GET /articles/1/author HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### Create Encoder Instance with Schema Mapping

Source: https://github.com/neomerx/json-api/wiki/Home

This example shows how to create an Encoder instance by passing an array mapping resource types to schema providers. The mapping can use class name strings, ::class constants, schema instances, or callables.

```php
$encoder = Encoder::instance([
    // class names as strings
    '\Author'      => '\AuthorSchema',

    // '::class' constant (PHP 5.5+) convenient for classes in namespaces
    Comment::class => CommentSchema::class,

    // Schema instances could be used as well
    Post::class    => $postSchema,

    // callables are also supported
    Site::class    => function (FactoryInterface $factory) use (...) {
        $schema = new SiteSchema($factory, ..., ..., ...);
        return $schema;
    }
]);
```

--------------------------------

### 201 Created response for photo creation

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example response when a photo is created successfully. Includes the Location header and the created resource document with its self link.

```http
HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "links": {
      "self": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}
```

--------------------------------

### Parsing Accept and Content-Type Headers

Source: https://github.com/neomerx/json-api/wiki/Parsing-API-Parameters

Demonstrates parsing HTTP headers using HeaderParametersParser. The example parses an Accept header value and a Content-Type header value, returning media type objects.

```php
use Neomerx\JsonApi\Contracts\Http\Headers\AcceptHeaderInterface;
use Neomerx\JsonApi\Factories\Factory;
use Neomerx\JsonApi\Http\Headers\AcceptHeader;

$parser = new HeaderParametersParser(new Factory());

$acceptValue = 'foo/bar.baz;media=param;q=0.5;ext="ext1,ext2", type/*, */*';
foreach($parser->parseAcceptHeader($acceptValue) as $acceptMediaType) {
    ...
}

$contentTypeValue = 'application/vnd.api+json';
$contentMediaType = $parser->parseContentTypeHeader($contentTypeValue);
```

--------------------------------

### Link constructor with isSubUrl, value, hasMeta, and meta parameters

Source: https://github.com/neomerx/json-api/wiki/Links

Constructor declaration for the Link class. The $isSubUrl parameter controls whether the URL is treated as a sub-url and gets prefixed; set it to false to avoid prefixing. $value is typically a partial URL like '/authors' that gets merged with other parts.

```php
/**
 * @param bool   $isSubUrl If $value is a sub-url and encoder should add a URL prefix to it.
 * @param string $value    URL value.
 * @param bool   $hasMeta  If links has meta information.
 * @param mixed  $meta     Meta information.
 */
public function __construct(bool $isSubUrl, string $value, bool $hasMeta, $meta = null)
```

--------------------------------

### HTTP request with profile media type parameter

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example HTTP request that asks the server to apply the http://example.com/last-modified and http://example.com/timestamps profiles. The Accept header includes the profile parameter with a space-separated list of profile URIs, quoted because it contains more than one URI.

```http
GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json; profile="http://example.com/last-modified http://example.com/timestamps"
```

--------------------------------

### GET empty to-many relationship link response

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example response for a GET request to a to-many relationship link URL when the relationship is empty, returning an empty data array.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/tags",
    "related": "/articles/1/tags"
  },
  "data": []
}
```

--------------------------------

### JSON document illustrating meta locations

Source: https://github.com/neomerx/json-api/wiki/Schemas

A JSON example showing where meta information can be placed in a JSON API document: at the document level, in resource, in linkage, and in relationship meta.

```json
{
    "meta": {"here": "document meta"},
    "data":{
        "type":"posts",
        "id":"1",
        "attributes":{
        },
        "relationships":{
            "author":{
                "data":{
                    "type":"people",
                    "id":"9",
                    "meta": {"here": "linkage meta"}
                },
                "meta": {"here": "relationship meta"}
            }
        },
        "meta": {"here": "resource meta"}
    }
}
```

--------------------------------

### GET /articles/1

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Fetches an individual article. Returns a 200 OK response with a resource object or null as primary data.

```APIDOC
## GET /articles/1

### Description
Fetches an individual article. The response contains a resource object or null as primary data.

### Method
GET

### Endpoint
/articles/1

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the article.

### Request Example
GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (object|null) - Resource object or null.
- **links** (object) - Contains self link.

#### Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "related": "http://example.com/articles/1/author"
        }
      }
    }
  }
}
```

--------------------------------

### 200 OK Response for Fetching an Individual Resource

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example 200 OK responses for fetching an individual resource and a related resource when the relationship is empty. The primary data is a resource object or null.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "related": "http://example.com/articles/1/author"
        }
      }
    }
  }
}
```

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1/author"
  },
  "data": null
}
```

--------------------------------

### GET /articles

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Fetches a collection of articles. Returns a 200 OK response with an array of resource objects or an empty array as primary data.

```APIDOC
## GET /articles

### Description
Fetches a collection of articles. The response contains an array of resource objects or an empty array as primary data.

### Method
GET

### Endpoint
/articles

### Parameters
#### Query Parameters
- None specified.

### Request Example
GET /articles HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array) - Array of resource objects or empty array.
- **links** (object) - Contains self link.

#### Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    }
  }, {
    "type": "articles",
    "id": "2",
    "attributes": {
      "title": "Rails is Omakase"
    }
  }]
}
```

--------------------------------

### 200 OK Response for Fetching a Collection

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example 200 OK responses for fetching a collection of articles and an empty collection. The primary data is an array of resource objects or an empty array.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    }
  }, {
    "type": "articles",
    "id": "2",
    "attributes": {
      "title": "Rails is Omakase"
    }
  }]
}
```

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": []
}
```

--------------------------------

### GET /people?sort=age,name

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Requests that the primary data be sorted by multiple sort fields in the order specified.

```APIDOC
## [GET] /people?sort=age,name

### Description
Requests that the primary data be sorted by multiple sort fields in the order specified.

### Method
GET

### Endpoint
/people?sort=age,name

### Parameters
#### Query Parameters
- **sort** (string) - Required - Comma-separated list of sort fields. Sort fields are applied in the order specified.

### Request Example
GET /people?sort=age,name HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array) - The resource collection sorted by the specified fields.

#### Response Example
{
  "data": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "name": "John",
        "age": 25
      }
    }
  ]
}
```

--------------------------------

### GET /articles?sort=-created,title

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Requests that the primary data be sorted by the created field in descending order, then by title in ascending order.

```APIDOC
## [GET] /articles?sort=-created,title

### Description
Requests that the primary data be sorted by the created field in descending order, then by title in ascending order.

### Method
GET

### Endpoint
/articles?sort=-created,title

### Parameters
#### Query Parameters
- **sort** (string) - Required - Comma-separated list of sort fields. Prefix a field with a minus (-) for descending order.

### Request Example
GET /articles?sort=-created,title HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array) - The resource collection sorted by the specified fields.

#### Response Example
{
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "JSON:API paints my bikeshed!",
        "created": "2023-01-01T00:00:00Z"
      }
    }
  ]
}
```

--------------------------------

### Fetching Relationships with GET Requests

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

HTTP requests to fetch relationship data for an article's comments and author. Each request uses the Accept header application/vnd.api+json.

```http
GET /articles/1/relationships/comments HTTP/1.1
Accept: application/vnd.api+json
```

```http
GET /articles/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### Article resource with self link

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example JSON:API document showing a resource object with a self link in its links member. The self link identifies the resource represented by the resource object.

```json
// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "links": {
    "self": "http://example.com/articles/1"
  }
}
// ...
```

--------------------------------

### Expected JSON output for encoded author

Source: https://github.com/neomerx/json-api/blob/master/README.md

This is the expected JSON output from the encoder example. It shows the structure with data type, id, attributes, relationships, and links, including the URL prefix applied to links.

```json
{
    "data" : {
        "type"       : "people",
        "id"         : "123",
        "attributes" : {
            "first-name": "John",
            "last-name": "Doe"
        },
        "relationships" : {
            "comments" : {
                "links": {
                    "related" : "http://example.com/api/v1/people/123/comments"
                }
            }
        },
        "links" : {
            "self" : "http://example.com/api/v1/people/123"
        }
    }
}
```

--------------------------------

### Sample encoded error JSON

Source: https://github.com/neomerx/json-api/wiki/Home

Example JSON output from encoding an error object, showing the structure with id, links, status, code, title, detail, source, and meta fields.

```json
{
    "errors":[{
        "id"     : "some-id",
        "links"  : {
            "about" : "about-link",
             "type" : [{ "href": "http://example.com/errors/123", "aliases": {"v": "version"} }]
        },
        "status" : "some-status",
        "code"   : "some-code",
        "title"  : "some-title",
        "detail" : "some-detail",
        "source" : {"source" : "data"},
        "meta"   : {"some" : "meta"}
    }]
}
```

--------------------------------

### Add relationship meta with self::RELATIONSHIP_META in PHP

Source: https://github.com/neomerx/json-api/wiki/Schemas

Shows how to add meta information to a relationship by using the `self::RELATIONSHIP_META` key in the `getRelationships` method of a schema class. The example includes a placeholder `...` for other relationships and methods.

```php
class SiteSchema extends BaseSchema
{
    ...

    public function getRelationships($site): : iterable
    {
        /** @var Site $site */
        return [
            ...
            'posts' => [
                self::RELATIONSHIP_META => ['description' => 'any meta information'],
            ],
            ...
        ];
    }
    
    ...
}
```

--------------------------------

### GET /articles/1/relationships/comments

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Fetches relationship data for an article's comments. Returns a 200 OK response with the appropriate resource linkage.

```APIDOC
## GET /articles/1/relationships/comments

### Description
Fetches relationship data for an article's comments. The response contains the appropriate resource linkage.

### Method
GET

### Endpoint
/articles/1/relationships/comments

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the article.

### Request Example
GET /articles/1/relationships/comments HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array|object|null) - Resource linkage matching the relationship type.
- **links** (object) - May contain self and related links.

#### Response Example
(No explicit example provided in source.)
```

--------------------------------

### JSON API response with self and related links

Source: https://github.com/neomerx/json-api/wiki/Schemas

Example JSON API document showing the resulting relationships object when self and related links are enabled. The links are generated based on the resource type and id.

```json
{
    "data": {
        "type": "sites",
        "id": "1",
        "attributes": { ... },
        "relationships": {
            "posts": {
                "data": { "type": "posts", "id": "321" },
                "links": {
                    "self": "http://example.com/sites/1/relationships/posts",
                    "related": "http://example.com/sites/1/posts"
                }
            }
        }
        ...
    }
}
```

--------------------------------

### Article with author relationship and links

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Example JSON:API document showing an article resource with an author relationship. The relationship includes a self link for the relationship, a related resource link, and linkage data (resource identifier object). The resource also has a self link.

```json
// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "http://example.com/articles/1/relationships/author",
        "related": "http://example.com/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  },
  "links": {
    "self": "http://example.com/articles/1"
  }
}
// ...
```

--------------------------------

### Schema returning a proxy object

Source: https://github.com/neomerx/json-api/wiki/Extending-Encoder

Example schema that returns an AuthorProxy object (subclass of Author) for the 'author' relationship, which would normally cause a type mismatch.

```php
class PostSchema extends BaseSchema
{
    ...

    public function getRelationships($post): iterable
    {
        return [
            'author' => [
                // will not return an Author object but
                // AuthorProxy which extends Author
                self::RELATIONSHIP_DATA => $post->getAuthor() 
            ]
        ];
    }
    
    ...
}
```

--------------------------------

### JSON API link object with URL string and meta object

Source: https://github.com/neomerx/json-api/wiki/Links

Shows the two allowed representations of a link object in a JSON API document: a URL string and an object with href and meta. The example includes a self link as a string and a related link with meta information.

```json
"links": {
    "self": "http://example.com/articles/1",
    "related": {
        "href": "http://example.com/articles/1/comments",
        "meta": {
            "count": 10
        }
    }
}
```

--------------------------------

### GET /articles?include=author&fields[articles]=title,body&fields[people]=name

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Requests that the endpoint return only specific fields for each resource type using the fields[TYPE] query parameter. The value must be a comma-separated list of field names.

```APIDOC
## [GET] /articles?include=author&fields[articles]=title,body&fields[people]=name

### Description
Requests that the endpoint return only specific fields for each resource type using the fields[TYPE] query parameter. The value must be a comma-separated list of field names.

### Method
GET

### Endpoint
/articles?include=author&fields[articles]=title,body&fields[people]=name

### Parameters
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of related resources to include.
- **fields[articles]** (string) - Optional - Comma-separated list of field names to return for articles.
- **fields[people]** (string) - Optional - Comma-separated list of field names to return for people.

### Request Example
GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array) - The requested resource objects with only the specified fields.

#### Response Example
{
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "JSON:API paints my bikeshed!",
        "body": "The shortest article. Ever."
      }
    }
  ]
}
```

--------------------------------

### AuthorSchema class definition

Source: https://github.com/neomerx/json-api/blob/master/README.md

This schema class extends BaseSchema and defines how to map an author object to JSON API. It provides the type, id, attributes, and relationships. The relationships include a comments link and optionally data, with a commented-out example.

```php
class AuthorSchema extends BaseSchema
{
    public function getType(): string
    {
        return 'people';
    }

    public function getId($author): ?string
    {
        return $author->authorId;
    }

    public function getAttributes($author, ContextInterface $context): iterable
    {
        return [
            'first-name' => $author->firstName,
            'last-name'  => $author->lastName,
        ];
    }

    public function getRelationships($author, ContextInterface $context): iterable
    {
        return [
            'comments' => [
                self::RELATIONSHIP_LINKS_SELF    => false,
                self::RELATIONSHIP_LINKS_RELATED => true,

                // Data include supported as well as other cool features
                // self::RELATIONSHIP_DATA => $author->comments,
            ],
        ];
    }
}
```

--------------------------------

### Run the sample application

Source: https://github.com/neomerx/json-api/blob/master/sample/README.md

Runs the sample application, which outputs encoding results for resources with and without relationships, sparse field sets, and top-level links and meta information.

```bash
$ php sample.php
```

--------------------------------

### Run Blackfire profiling command

Source: https://github.com/neomerx/json-api/blob/master/perf/readme.md

Use this command to profile the sample script with Blackfire. The first run downloads Docker images, which takes time; subsequent runs are faster. The output includes basic performance info and a URL to detailed profiling results.

```bash
$ docker-compose run --rm cli_php blackfire run php -d zend.assertions=-1 /app/sample/sample.php -t=100
```

--------------------------------

### Run performance test with default parameters

Source: https://github.com/neomerx/json-api/blob/master/sample/README.md

Runs the performance test with default parameters.

```bash
$ php sample.php -t
```

--------------------------------

### GET /people?sort=age

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Requests that the primary data be sorted by the specified sort field in ascending order.

```APIDOC
## [GET] /people?sort=age

### Description
Requests that the primary data be sorted by the specified sort field in ascending order.

### Method
GET

### Endpoint
/people?sort=age

### Parameters
#### Query Parameters
- **sort** (string) - Required - The sort field. Prefix with a minus (-) for descending order.

### Request Example
GET /people?sort=age HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array) - The resource collection sorted by the specified field.

#### Response Example
{
  "data": [
    {
      "type": "people",
      "id": "1",
      "attributes": {
        "name": "John",
        "age": 25
      }
    }
  ]
}
```

--------------------------------

### GET /articles/1/author

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Fetches the author of an article. Returns a 200 OK response with a resource object or null as primary data.

```APIDOC
## GET /articles/1/author

### Description
Fetches the author of an article. The response contains a resource object or null as primary data.

### Method
GET

### Endpoint
/articles/1/author

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the article.

### Request Example
GET /articles/1/author HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (object|null) - Resource object or null.
- **links** (object) - Contains self link.

#### Response Example
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1/author"
  },
  "data": null
}
```

--------------------------------

### Creating HTTP Responses with BaseResponses

Source: https://github.com/neomerx/json-api/wiki/Parsing-API-Parameters

Shows how to use the BaseResponses class to create a response for a newly created resource with HTTP code 201 and a 'location' header. The Responses class should extend Neomerx\JsonApi\Http\BaseResponses.

```php
// `Responses` should extend `Neomerx\JsonApi\Http\BaseResponses`
$responses = new Responses(...);

// response for newly created resource with
// HTTP code 201 + 'location' header
$response = $responses->getCreatedResponse($newAuthor);
```

--------------------------------

### Run performance tests for PHP 7.1-7.4

Source: https://github.com/neomerx/json-api/blob/master/sample/README.md

Runs the performance test in PHP 7.1, 7.2, 7.3, and 7.4 using docker-compose. Each command targets a specific PHP version.

```bash
$ composer perf-test-php-7-1
```

```bash
$ composer perf-test-php-7-2
```

```bash
$ composer perf-test-php-7-3
```

```bash
$ composer perf-test-php-7-4
```

--------------------------------

### Define a Schema with getType, getId, getAttributes, getRelationships

Source: https://github.com/neomerx/json-api/wiki/Schemas

Sample schema extending BaseSchema that defines a resource type, id, attributes, and relationships. Shows how to use RELATIONSHIP_DATA, RELATIONSHIP_LINKS_SELF, and RELATIONSHIP_LINKS_RELATED constants.

```php
class AuthorSchema extends BaseSchema
{
    public function getType(): string
    {
        return 'people';
    }

    public function getId($author): ?string
    {
        return $author->authorId;
    }

    public function getAttributes($author): iterable
    {
        return [
            'first-name' => $author->firstName,
            'last-name'  => $author->lastName,
        ];
    }

    public function getRelationships($author): iterable
    {
        return [
            'comments' => [
                self::RELATIONSHIP_DATA          => $author->comments,
                self::RELATIONSHIP_LINKS_SELF    => false,
                self::RELATIONSHIP_LINKS_RELATED => true,
            ],
        ];
    }
}
```

--------------------------------

### GET /articles/1/relationships/author

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Fetches relationship data for an article's author. Returns a 200 OK response with the appropriate resource linkage.

```APIDOC
## GET /articles/1/relationships/author

### Description
Fetches relationship data for an article's author. The response contains the appropriate resource linkage.

### Method
GET

### Endpoint
/articles/1/relationships/author

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the article.

### Request Example
GET /articles/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json

### Response
#### Success Response (200)
- **data** (array|object|null) - Resource linkage matching the relationship type.
- **links** (object) - May contain self and related links.

#### Response Example
(No explicit example provided in source.)
```

--------------------------------

### Custom Container, Factory, and Encoder implementation

Source: https://github.com/neomerx/json-api/wiki/Extending-Encoder

Full implementation showing how to extend the encoder by overriding getResourceType, createSchemaContainer, and createFactory to handle proxy classes.

```php
use Doctrine\Common\Util\ClassUtils;
use Neomerx\JsonApi\Encoder\Encoder;
use Neomerx\JsonApi\Schema\SchemaContainer;
use Neomerx\JsonApi\Factories\Factory;

class YourContainer extends SchemaContainer
{
    protected function getResourceType($resource)
    {
        return ClassUtils::getRealClass(get_class($resource));
    }
}

class YourFactory extends Factory
{
    public function createSchemaContainer(iterable $schemas): SchemaContainerInterface
    {
        return new YourContainer($this, $schemas);
    }
}

class YourEncoder extends Encoder
{
    protected static function createFactory(): FactoryInterface
    {
        return new YourFactory();
    }
}
```

--------------------------------

### withUrlPrefix(string $prefix): self

Source: https://github.com/neomerx/json-api/wiki/Home

Sets a URL prefix for all links in the document.

```APIDOC
## withUrlPrefix(string $prefix): self

### Description
Sets a URL prefix for all links in the document.

### Method
withUrlPrefix

### Parameters
- **$prefix** (string) - Required - The URL prefix to prepend to links.

### Returns
- **self** - The encoder instance for chaining.

### Example
```php
$encoder->withUrlPrefix('http://example.com');
```
```

--------------------------------

### DELETE resource request

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Deletes an individual resource by sending a DELETE request to the resource's URL. The example deletes photo with ID 1.

```http
DELETE /photos/1 HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### Run tests with composer test

Source: https://github.com/neomerx/json-api/wiki/Testing-and-Performance

Runs the project's test suite via Composer. Use this command to execute all tests defined in the composer.json scripts.

```bash
$ composer test
```

--------------------------------

### LinkInterface Constants

Source: https://github.com/neomerx/json-api/wiki/Links

Documentation for the predefined constants in LinkInterface.

```APIDOC
## LinkInterface Constants

### Description
Predefined constants for common link keys.

### Constants
- `SELF`
- `RELATED`
- `FIRST`
- `LAST`
- `NEXT`
- `PREV`
- `ABOUT`

### Usage
These constants can be used as link keys. You are not limited to these constants and can use any valid JSON string values as link keys.
```

--------------------------------

### Link::__construct

Source: https://github.com/neomerx/json-api/wiki/Links

Documentation for the Link class constructor, which supports both URL string and object representations.

```APIDOC
## Link Constructor

### Description
Creates a new Link object that can represent a URL string or an object with meta information.

### Method
Constructor

### Endpoint
`Link::__construct`

### Parameters
- **$isSubUrl** (bool) - Required - If `$value` is a sub-url and encoder should add a URL prefix to it.
- **$value** (string) - Required - URL value.
- **$hasMeta** (bool) - Required - If links has meta information.
- **$meta** (mixed) - Optional - Meta information.

### Request Example
```php
new Link(true, '/authors', false);
```

### Response
No return value (constructor).
```

--------------------------------

### Encode data with links, meta, and field sets

Source: https://github.com/neomerx/json-api/wiki/Home

Shows how to configure the encoder with options, URL prefix, top-level links, meta, included paths, and field sets before encoding a resource. The $links array uses Link constants for pagination links, and $meta can be any json_encode-able type.

```php
$isSubUrl = false;
$hasMeta  = false;
$links    = [
    Link::FIRST => new Link($isSubUrl,'http://example.com/sites?first', $hasMeta),
    Link::LAST  => new Link($isSubUrl,'http://example.com/sites?last', $hasMeta),
    Link::PREV  => new Link($isSubUrl,'http://example.com/sites?prev', $hasMeta),
    Link::NEXT  => new Link($isSubUrl,'http://example.com/sites?next', $hasMeta),
];

$result = $encoder
    ->withEncodeOptions(JSON_PRETTY_PRINT)
    ->withUrlPrefix('http://example.com')
    ->withLinks($links)
    ->withMeta($meta)
    ->withIncludedPaths([
        'posts',
        'posts.author',
        'posts.comments',
    ])
    ->withFieldSets([
        // Attributes and relationships that should be shown
        'sites'  => ['name', 'posts'],
        'posts'  => ['author'],
        'people' => ['first_name'],
    ])
    ->encodeData($site);
```

--------------------------------

### Run performance test with time measurement and iterations

Source: https://github.com/neomerx/json-api/blob/master/sample/README.md

Runs the performance test with execution time measurement and a specified number of iterations (10000).

```bash
$ time php sample.php -t=10000
```

--------------------------------

### Quick fix for proxy class mapping

Source: https://github.com/neomerx/json-api/wiki/Extending-Encoder

Quick fix that maps both the Author and AuthorProxy classes to the same schema, avoiding the need for a custom container.

```php
// quick fix
$encoder = Encoder::instance([
    Author::class       => AuthorSchema::class,
    AuthorProxy::class  => AuthorSchema::class,
]);
```

--------------------------------

### POST /photos

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Creates a new resource by sending a POST request to a collection URL. The request must include a single resource object as primary data with at least a type member. Optionally, a client-generated ID can be provided.

```APIDOC
## [POST] /photos

### Description
Creates a new resource by sending a POST request to a collection URL. The request must include a single resource object as primary data with at least a type member. Optionally, a client-generated ID can be provided.

### Method
POST

### Endpoint
/photos

### Parameters
#### Request Body
- **data** (object) - Required - The primary resource object.
  - **type** (string) - Required - The resource type.
  - **id** (string) - Optional - Client-generated ID (UUID) if supported.
  - **attributes** (object) - Optional - Resource attributes.
  - **relationships** (object) - Optional - Resource relationships.
    - **data** (object) - Required - Relationship linkage.
      - **type** (string) - Required - Related resource type.
      - **id** (string) - Required - Related resource ID.

### Request Example
{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}

### Response
#### Success Response (201 Created)
- **data** (object) - The created resource object.
  - **type** (string) - Resource type.
  - **id** (string) - Resource ID.
  - **attributes** (object) - Resource attributes.
  - **links** (object) - Resource links.
    - **self** (string) - Self link.

#### Response Example
{
  "data": {
    "type": "photos",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "links": {
      "self": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

#### Error Responses
- **202 Accepted** - Request accepted for processing, but not yet completed.
- **204 No Content** - Created successfully with client-generated ID, no response document.
- **403 Forbidden** - Unsupported request to create a resource.
- **404 Not Found** - Related resource does not exist.
- **409 Conflict** - Client-generated ID already exists.
```

--------------------------------

### LinkWithAliases::__construct

Source: https://github.com/neomerx/json-api/wiki/Links

Documentation for the LinkWithAliases class constructor, which extends Link to support aliases.

```APIDOC
## LinkWithAliases Constructor

### Description
Class `LinkWithAliases` has an extra parameter to support JSON API aliases feature.

### Method
Constructor

### Endpoint
`LinkWithAliases::__construct`

### Parameters
- **$isSubUrl** (bool) - Required - If `$value` is a sub-url and encoder should add a URL prefix to it.
- **$value** (string) - Required - URL value.
- **$hasMeta** (bool) - Required - If links has meta information.
- **$meta** (mixed) - Optional - Meta information.
- **$aliases** (mixed) - Required - Aliases for the link.

### Request Example
```php
new LinkWithAliases(true, '/authors', false, null, $aliases);
```

### Response
No return value (constructor).
```

--------------------------------

### Schema $selfSubUrl default construction (0.6.5)

Source: https://github.com/neomerx/json-api/wiki/Upgrade-Notes

In version 0.6.5, the $selfSubUrl field in Schema became optional. By default it is constructed as shown. If you specify $selfSubUrl, it will be checked that it starts and ends with '/'. For performance reasons, it is recommended to not set $selfSubUrl unless it differs from the default.

```php
    $this->selfSubUrl = '/' . $this->resourceType . '/';
```

--------------------------------

### Default implementations for getResourceLinks and getIncludedResourceLinks

Source: https://github.com/neomerx/json-api/wiki/Upgrade-Notes

Default implementations for the new getResourceLinks and getIncludedResourceLinks methods. These replace the $isShowSelf and $isShowSelfInIncluded fields; if you did not change those fields, no code changes are needed.

```php
public function getResourceLinks($resource)
{
    $links = [
        LinkInterface::SELF => $this->getSelfSubLink($resource),
    ];

    return $links;
}

public function getIncludedResourceLinks($resource)
{
    return [];
}
```

--------------------------------

### POST /photos - Create a new photo resource

Source: https://github.com/neomerx/json-api/blob/master/spec/current.txt

Sends a POST request to create a new photo resource. The request body includes a single resource object with type, attributes, and relationships. The server must return 201 Created with the created resource or 202 Accepted if processing is not yet complete.

```http
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}
```

--------------------------------

### Schema Interface

Source: https://github.com/neomerx/json-api/wiki/Schemas

Documentation for the Schema interface in the neomerx/json-api library, covering methods and relationship configuration.

```APIDOC
## Schema Interface

### Description
A `Schema` is a class that implements `SchemaInterface` and provides information on how an arbitrary resource object(s) (class, Model, etc) should be converted to JSON API format. It gives information about resource attributes, relationships, resource id, JSON API type and URL, conversion settings, and relationship pagination links.

### Methods

#### `getType(): string`
Returns the JSON API resource type.

#### `getId($resource): ?string`
Returns the resource identifier.

#### `getAttributes($resource): iterable`
Returns an iterable of resource attributes.

#### `getRelationships($resource): iterable`
Returns an iterable of resource relationships.

### Relationship Configuration Keys

- `self::RELATIONSHIP_DATA` - The relationship data, can be a resource object or an `IdentifierInterface` instance.
- `self::RELATIONSHIP_LINKS_SELF` - Boolean, whether to show the `self` link for the relationship.
- `self::RELATIONSHIP_LINKS_RELATED` - Boolean, whether to show the `related` link for the relationship.
- `self::RELATIONSHIP_LINKS` - An array of custom links for the relationship, keyed by link name.

### Example Schema

```php
class AuthorSchema extends BaseSchema
{
    public function getType(): string
    {
        return 'people';
    }

    public function getId($author): ?string
    {
        return $author->authorId;
    }

    public function getAttributes($author): iterable
    {
        return [
            'first-name' => $author->firstName,
            'last-name'  => $author->lastName,
        ];
    }

    public function getRelationships($author): iterable
    {
        return [
            'comments' => [
                self::RELATIONSHIP_DATA          => $author->comments,
                self::RELATIONSHIP_LINKS_SELF    => false,
                self::RELATIONSHIP_LINKS_RELATED => true,
            ],
        ];
    }
}
```

### Using Identifiers in Relationships

To show a relationship with only an identifier (e.g., a foreign key), return an `IdentifierInterface` instance in `self::RELATIONSHIP_DATA`.

```php
use Neomerx\JsonApi\Schema\Identifier;

class CommentSchema extends BaseSchema
{
    public function getRelationships($comment): iterable
    {
        return [
            'author' => [
                self::RELATIONSHIP_DATA => new Identifier($comment->id_author, 'people'),
            ],
        ];
    }
}
```

### Show/Hide 'self' and 'related' URLs

Use `self::RELATIONSHIP_LINKS_SELF` and `self::RELATIONSHIP_LINKS_RELATED` to control the display of `self` and `related` links for each relationship.

```php
class SiteSchema extends BaseSchema
{
    public function getRelationships($site): iterable
    {
        return [
            'posts' => [
                self::RELATIONSHIP_DATA          => $site->posts,
                self::RELATIONSHIP_LINKS_SELF    => true,
                self::RELATIONSHIP_LINKS_RELATED => true,
            ],
        ];
    }
}
```

Example JSON output with `self` and `related` links:

```json
{
    "data": {
        "type": "sites",
        "id": "1",
        "attributes": { ... },
        "relationships": {
            "posts": {
                "data": { "type": "posts", "id": "321" },
                "links": {
                    "self": "http://example.com/sites/1/relationships/posts",
                    "related": "http://example.com/sites/1/posts"
                }
            }
        }
    }
}
```

### Custom Links in Relationships

Add custom links using the `self::RELATIONSHIP_LINKS` key. Links can be absolute or relative URLs.

```php
class SiteSchema extends BaseSchema
{
    public function getRelationships($site): iterable
    {
        return [
            'posts' => [
                self::RELATIONSHIP_DATA  => $site->posts,
                self::RELATIONSHIP_LINKS => [
                    LinkInterface::FIRST => new Link(false, 'http://example.com/posts?first', false),
                    'custom-link'        => new Link(false, 'http://example.com/custom-link', false),
                ],
            ],
        ];
    }
}
```
```
Tokens:
Raw