Framework agnostic JSON API (jsonapi.org) implementation
PHP
Latest commit fa87d69 Jan 18, 2017 @lunika lunika committed with Close #166
Enable php 7.1 in travis
Permalink
Failed to load latest commit information.
sample Close #155 Jul 27, 2016
src Close #162 Nov 12, 2016
tests Close #156 Aug 24, 2016
.editorconfig Initial commit Aug 5, 2015
.gitattributes Close #122 Mar 25, 2016
.gitignore Close #96 Nov 21, 2015
.scrutinizer.yml Initial commit Apr 22, 2015
.travis.yml Close #166 Jan 18, 2017
LICENSE Initial commit Apr 22, 2015
NOTICE Initial commit Apr 22, 2015
README.md Update Jul 26, 2016
composer.json Close #131 Apr 29, 2016
docker-compose.yml Close #131 Apr 29, 2016
phpunit.xml Initial commit Apr 22, 2015

README.md

Project Management Scrutinizer Code Quality Code Coverage Build Status HHVM 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.0 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

  • Resource attributes and relationships
  • Polymorphic resource data and relationships
  • Compound documents with inclusion of related resources (circular resource references supported)
  • Meta information for document, resources, errors, relationship and link objects
  • Parsing HTTP Accept and Content-Type headers in accordance with RFC 7231
  • Parsing parameters for pagination, sorting and filtering
  • Sparse fieldsets and customized included paths
  • Errors

High code quality and 100% test coverage with 200+ 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 Flute.

The server supports

  • CRUD operations for a few sample data models and Users.
  • Cross-origin requests (CORS) to API server.
  • Authentication (Bearer token) and authorizations for CRUD operations.
  • Support for such JSON API features as resource inclusion, pagination and etc.

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' => '\AuthorSchema',
], new EncoderOptions(JSON_PRETTY_PRINT, 'http://example.com/api/v1'));

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

will output

{
    "data": {
        "type": "people",
        "id": "123",
        "attributes": {
            "first_name": "John",
            "last_name": "Dow"
        },
        "links": {
            "self": "http://example.com/api/v1/people/123"
        }
    }
}

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

class AuthorSchema extends SchemaProvider
{
    protected $resourceType = 'people';

    public function getId($author)
    {
        /** @var Author $author */
        return $author->authorId;
    }

    public function getAttributes($author)
    {
        /** @var Author $author */
        return [
            'first_name' => $author->firstName,
            'last_name'  => $author->lastName,
        ];
    }
}

The first EncoderOptions parameter JSON_PRETTY_PRINT is a PHP predefined JSON constant.

The second EncoderOptions parameter http://example.com/api/v1 is a URL prefix that will be applied to all encoded links unless they have $treatAsHref flag set to true.

For more advanced usage please check out the Wiki.

Questions?

Do not hesitate to contact us on Gitter or post an issue.

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.

Current tasks are managed with Waffle.io.

There are 2 ways to send pull requests

  • small pull requests should be sent to develop branch as 1 commit
  • for bigger pull requests (e.g. new features) it's recommended to create an issue requesting a new branch for that feature. When a new branch named feature/issueXX is created (where XX is the issue number) you should post pull requests to this branch. When the feature is completed the branch will be squashed and merged to develop and then to master branches.

License

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