Rename library to json-api-response

[tobyzerner]

tobscure/json-api is very a non-specific name, it doesn't really tell you what the library does. In #121 I've said I want to keep the scope of this library quite narrow (building JSON-API documents using dynamic data) so maybe it would be wise to rename accordingly?

Options:

• tobscure/json-api-builder
• tobscure/json-api-serializer (not quite... it does more than just serialize)
• tobscure/json-api-server (it's less than a server - there is no HTTP stuff)
• tobscure/json-api-response
• ???

Also note that I plan to extract some of Flarum's JSON-API consumption JavaScript into an accompanying library called tobscure/json-api-store.

/cc @f3ath @franzliedke

[f3ath]

mmm dunno... IMO builder has connotations with the Builder pattern from PoEAA. Maybe json-api-response?

[tobyzerner]

json-api-response could work... especially since we have the Parameters utility which aids in the construction of a document in response to a request

[tobyzerner]

The Builder pattern is not too far off though, is it?

... the builder pattern uses another object, a builder, that receives each initialization parameter step by step and then returns the resulting constructed object at once.

$document->setInclude(['author', 'comments']);
$document->setFields(['posts' => ['title', 'body']]);
$document->setMetaItem('total', count($posts));

$document->jsonSerialize(); // constructs a json object

Or what about json-api-factory? Or json-api-response-factory

[f3ath]

Same thing about Factory :) But actually disregard, it's just my idiosyncrasy, I guess.

[tobyzerner]

:P I think I like json-api-response anyway, doesn't get much clearer than that

Will await @franzliedke's opinion

[franzliedke]

My previous endeavors with writing JSON-API libraries have shown me that supporting both the building and parsing of JSON-API payloads is actually quite useful, i.e. for filtering valid attributes when POSTing JSON-API stuff.

But if that's outside the scope that you want to support (don't we need something like that for Flarum?) then yes, json-api-response feels fitting.

[tobyzerner]

@franzliedke You might be right, but I'd argue that parsing requests is very much unrelated to building responses and would be better suited to a separate library.

In any case, got me brainstorming for a potential tobscure/json-api-request library:

use Tobscure\JsonApiRequest\ResourceSchema;
use Tobscure\JsonApiRequest\UpdateResourceDocument;

$schema = new ResourceSchema('posts');
$schema->setAttributes(['title', 'body']);
$schema->setToOneRelationships([
    'author' => ['users', 'companies']
]);
$schema->setToManyRelationships([
    'tags' => ['tags']
]);

// OR

class PostSchema extends ResourceSchema
{
    protected $type = 'posts';
    protected $attributes = ['title', 'body'];
    protected $toOneRelationships = [
        'author' => ['users', 'companies']
    ];
    protected $toManyRelationships = [
        'tags' => ['tags']
    ];
}
$schema = new PostSchema();

// validate document structure + contents according to schema,
// make sure resource ID matches
$document = UpdateResourceDocument::fromJson($json, $schema, '1');

$resource = $document->getData();

$attributes = $resource->getAttributes();
// perform custom validation on attributes here

$author = $resource->getToOneRelationship('author');
$tags = $resource->getToManyRelationship('tags');

foreach ($tags->getLinkage() as $tag) {
    $tagIds[] = $tag->getId();
}

[franzliedke]

Well, I have had a good experience with defining my entities in one place and using that for both serializing and parsing.

Doing both would also mean we can focus on that stuff, basically building an opinionated abstraction on top of the low-level stuff implemented in @f3ath's library.

[tobyzerner]

@franzliedke care to share some pseudo-code of your entity definitions?

It sounds like you have a much better idea of how this would work than I do, I need to understand before I can make a decision :)

[franzliedke]

Sure. It's Ruby, so it is pretty close to pseudo-code anyway ;)

entity do
  type 'discussions'

  writable attribute('title') {
    description 'The discussion title'
    type String
  }

  writable attribute('text') {
    description 'Discussion text'
    type String
    alias_for 'content_text'
  }

  writable attribute('author_name') {
    description 'The author\'s display name'
    type String
    reading { |discussion| "#{discussion['author_first_name']} #{discussion['author_last_name']}" }
    writing { |value|
      parts = value.split ' '
      { author_first_name: parts[0], author_last_name: parts[1] }
    } 
  }

  includable has_one('tag', TagResource) {
    embedded { |discussion| discussion['tag'] }
  }

  includable has_many('posts', PostResource) {
    filter_by 'discussion'
  }

  link('self') { |discussion| "/api/discussions/#{discussion['id']}" }
end

filters do
  optional 'tag' do
    description 'Only return discussions belonging to this tag'
  end
end

paginate! per_page: 25

collection do
  get 'List all discussions' do
    # Load all discussions
  end
end

member do
  get 'Get information about a discussion' do
    # Code for loading a discussion
  end
end

First of all, the entity block:

• describes the structure of a "discussion" entity
• is used for generating API documentation (hence the type and human-readable description)
• takes care of mapping to and from the data source (in our case it is backend services, here it would be a database) - alias_for maps to a different name in the hash that is sent to / received from the data source, reading and writing are used for less trivial decoration tasks
• declaratively lists relationships and links

The member and collection blocks define the HTTP methods (this is probably out of scope for your library, I am just listing it for completeness' sakes) that are available for the entire collection / a member resource. In those blocks, the following methods are available:

• for writable requests, resource maps the input (a JSON-API request body) to a hash with only the allowed keys (i.e. attributes marked as writable) and applies all transformations (alias_for and all writing transformers)
• for readable requests, filters (for the collection) returns a hash with all allowed filters, again mapped using aliases, if available; and id (for members) is the ID from the URL
  When those blocks return a hash, this is then serialized in JSON-API format using the entity definition.

I hope that helps a bit. :)

[tobyzerner]

@franzliedke ah I see, thanks!

Hmm, what's the nicest way to replicate a declaration interface like that in PHP, especially where entities must reference each other (includable has_one('tag', TagResource))?

[tobyzerner]

How about something like this?

// defining entities
use Tobscure\JsonApi\Schema;

$postsSchema = new Schema('posts');
$tagsSchema = new Schema('tags');

$postsSchema->attribute('text')->aliasFor('content_text');
$postsSchema->hasMany('tags', $tagsSchema);

$tagsSchema->attribute('name');
$tagsSchema->hasMany('posts', $postsSchema);

// controller for GET /api/posts
use Tobscure\JsonApi\ListEndpoint;
use Tobscure\JsonApi\Parameters;

$endpoint = new ListEndpoint($postsSchema, function (Parameters $params) {
    return Posts::all()->load($params->getInclude());
});

// optionally set up extra parameters for validation
$endpoint->paginate(25);
$endpoint->addFilter('tag');
$endpoint->disallowInclude('tags');

$response = $endpoint->respond($_GET);
// validates provided params according to schema and endpoint configuration.
// gets raw data using callback provided.
// constructs response document from raw data according to schema and params.

// controller for GET /api/posts/{id}
use Tobscure\JsonApi\ShowEndpoint;
use Tobscure\JsonApi\Parameters;

$endpoint = new ShowEndpoint($postsSchema, function (Parameters $params) use ($id) {
    return Posts::find($id)->load($params->getInclude());
});

$response = $endpoint->respond($_GET);

// controller for POST /api/posts
use Tobscure\JsonApi\CreateEndpoint;

$endpoint = new CreateEndpoint($postsSchema, function ($attributes, $relationships) {
    return Post::create($attributes);
});

$response = $endpoint->respond($json, $_GET);
// validates provided JSON-API document and params according to schema.
// passes attributes and relationships to callback.
// constructs response document from returned raw data according to schema and params.

// controller for PATCH /api/posts/{id}
use Tobscure\JsonApi\UpdateEndpoint;

$endpoint = new UpdateEndpoint($postsSchema, function ($attributes, $relationships) use ($id) {
    $post = Post::find($id);
    $post->update($attributes);
    return $post;
});

$response = $endpoint->respond($json, $_GET);

// outputting response
$document = $response->getDocument();
http_response_code($response->getStatusCode());
header('Content-Type: ' . $document::MEDIA_TYPE);
echo json_encode($document);

// example of a Flarum API controller
final class ListPostsController extends AbstractListController
{
    private $posts;

    public function __construct(SchemaProvider $schemas, Post $posts)
    {
        parent::__construct($schemas->get('posts'));

        $this->posts = $posts;
    }

    public function configure(ListEndpoint $endpoint)
    {
        $endpoint->paginate(25);
        $endpoint->addFilter('tag');
        $endpoint->disallowInclude('tags');
    }

    public function data(Parameters $params)
    {
        return $this->posts->all()->load($params->getInclude());
    }
}

[tobyzerner]

@franzliedke ping :D