neomerx / json-api

Framework agnostic JSON API (jsonapi.org) implementation
Apache License 2.0
743 stars 66 forks source link

Build Status Scrutinizer Code Quality Code Coverage License

Description

JSON API logo

A good API is one of most effective ways to improve the experience for your clients. Standardized approaches for data formats and communication protocols increase productivity and make integration between applications smooth.

This framework agnostic package implements JSON API specification version v1.1 and helps focusing on core application functionality rather than on protocol implementation. It supports document structure, errors, data fetching as described in JSON API Format and covers parsing and checking HTTP request parameters and headers. For instance it helps to correctly respond with Unsupported Media Type (HTTP code 415) and Not Acceptable (HTTP code 406) to invalid requests. You don't need to manually validate all input parameters on every request. You can configure what parameters are supported by your services and this package will check incoming requests automatically. It greatly simplifies API development and fully support specification. In particular

High code quality and 100% test coverage with 150+ tests. Production ready.

To find out more, please check out the Wiki and Sample App.

“I'm loving how easy it makes it to quickly implement an api”

Jeremy Cloutier

Full-stack Integration

This package is framework agnostic and if you are looking for practical usage sample you might be interested in Quick start JSON API server application Limoncello App.

The server supports

Demo app screen-shot

Sample usage

Assuming you've got an $author of type \Author you can encode it to JSON API as simple as this

$encoder = Encoder::instance([
        Author::class => AuthorSchema::class,
    ])
    ->withUrlPrefix('http://example.com/api/v1')
    ->withEncodeOptions(JSON_PRETTY_PRINT);

echo $encoder->encodeData($author) . PHP_EOL;

will output

{
    "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"
        }
    }
}

The AuthorSchema provides information about resource's attributes and might look like

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,
            ],
        ];
    }
}

Parameter http://example.com/api/v1 is a URL prefix that will be applied to all encoded links unless they have a flag set telling not to add any prefixes.

Parameter JSON_PRETTY_PRINT is a PHP predefined JSON constant.

A sample program with encoding of multiple, nested, filtered objects and more is here.

For more advanced usage please check out the Wiki.

Versions

Current version is 4.x (PHP 7.1+) for older PHP (PHP 5.5 - 7.0, HHVM) please use version 1.x.

Questions?

Do not hesitate to check issues or post a new one.

Need help?

Are you planning to add JSON API and need help? We'd love to talk to you sales@neomerx.com.

Contributing

If you have spotted any specification changes that are not reflected in this package please post an issue. Pull requests for documentation and code improvements are welcome.

There are 2 ways to send pull requests

License

Apache License (Version 2.0). Please see License File for more information.