Feedback Request

[f3ath]

Hi there! The goal of this library is to implement the business rules of JSON API Specification v1.0 in php 7. There are 2 main principles I want to follow.

• Every single rule of the specification must be clearly expressed through object behavior. It should be impossible to produce an invalid JSON API document with this library.
• Pure and strict TDD. Not just "test first". Not only following the 3 rules of TDD. Not 100% unit test coverage. The tests must be the only documentation for the internal API, and this documentation must be easy to read.

I'd like to know what you think @tobscure @fesor @enleur @kefzce @sleepytomcat @franzliedke @crhayes

[tobyzerner]

Interesting project! Thoughts:

• What is the intended use-case? ie, is this something that tobscure/json-api could/should use to construct JSON-API documents?

• My understanding of the current spec is that the only links allowed are self and related, so should this be made explicit in the API:

$author->setSelfLink('/articles/1/relationships/author');
// instead of
$author->setLink('self', '/articles/1/relationships/author');

Can the consumer be expected to know that the name of the self link is indeed 'self', or should it just know about a setSelfLink method? You've kind of done this with Document::setApiVersion and Document::setApiMeta. (Want to know your thoughts about this because it's relevant to tobscure/json-api too!)

• Should links be represented by Link objects vs. just passing $value and $meta to the setLink method?

• What about getter methods?

[f3ath]

Thanks @tobscure I appreciate it a lot.

• Intention. Well, TBH initially it was an attempt to answer the question "how would i implement the next version of tobscure/json-api" :) But I didn't want to be limited by php5, so it was like OK, let's just read the docs and express it as tests. Could it potentially be used by libraries like yours, i guess so.

• Links. Good point. Besides self and related there are at least pagination links. Also, it looks like the spec does not explicitly say about the names. But the grey block on the same page kind of implies that there are no other names at v1.0. I am uncertain about this, generally speaking. It may still be a good idea to have the link names expressed as method names, just as you've done.

• Getters. There is no use case for the so far. As long as your goal is to build JSON, they are not needed. Though, I can imagine a use case like Document::fromJsonString(...)->withMeta(...)->withData(...) where each with... method produces another immutable clone of the original object, thus allowing to intercept, parse, modify, and pass the request along. But no use for just getters I can see so far. Generally, I try to avoid getters as they tend to expose the details and the state of an object, breaking encapsulation.

[tobyzerner]

I'm intrigued by this, I'm trying to think if there are any concepts I can steal and put back into tobscure/json-api :P

Thoughts on using Link objects vs. just passing $value and $meta to the setLink method?

Fair point re: getters.

How do you plan to implement compound documents?

[f3ath]

Feel free to use any of this. Initially I had Link and Meta, but refactored them out eventually. They can resurrect when I will be implementing attribute name validation though. Compounds are #1 in the list.

[franzliedke]

I too would be interested in the exact difference in scope between this (when it's done) and Toby's project. :)

[f3ath]

@franzliedke I don't know the answer. They might get pretty close. As I said, it was an attempt to rethink the object model for Toby's project. So far you can consider it an exercise in expressing the specification in pure TDD, I guess.

[tobyzerner]

@franzliedke I've been thinking about this a lot, here's the difference:

This library is simply a way to represent a known, valid JSON-API document structure in PHP.

tobscure/json-api has more utility: it takes raw data and transforms it into a JSON-API document structure.

I've just refactored some parts of tobscure/json-api to decouple the first part from the last part. If this library supported PHP 5.x, theoretically we could use it internally to do that last part of representing/validating the document. Alas, it's not a huge burden to implement that ourselves — I'm just happy to have cleaner code now :)

[franzliedke]

Sounds great, the decoupling makes sense.

And I've been searching for a library that does only the specification logic and serialization for a long time. (In Ruby, though, hehe.)

If this turns out to become the base of Toby's library one day, maybe we can turn that into something more opinionated for structuring an API, somewhat like a micro-framework for JSON-API endpoints.

[f3ath]

I have just release v1.0.0. It has BC breaking changes compared to v0.7. I would appreciate your feedback on it. Hey @johnrobertporter, as an early adopter, your feedback would be especially useful.

Thanks, guys.

[ghost]

As I'm close to an MVP, I will have to feedback after release; maybe in a month or so. Definitely happy to do so though.

[f3ath]

Thanks @johnrobertporter good luck with your project.