Hey,

found a small issue in the detection of serializer's detection for resources. Actually I came across this because I got a warning wrapped into an exception containing Warning: array_udiff(): Argument #2 is not an array (JsonApiSerializationVisitor:170).

The issue should be fairly easy to reproduce:

• Create an entity with validation constraints
• Submit a request which causes a single field to fail (important!)
• You should see the above pasted warning.

Here's the deal: if you submit a request and validate a form, the default JMSSerializer obviously scans recursively through the data (the form) and its children to extract all errors. Field errors are nested and other errors are then in the root of the validation result. However, the data that is available inside the JsonApiSerializationVisitor is an ArrayObject in cases of validation errors (thus it is NOT an array) which causes the current implementation of validateJsonApiDocument already to return true; which is not intended. The warning above comes from an inconsistent error handling (there's already a todo) which does not handle error-cases where only children have messages (so that the key errors is not defined in the root level). In fact this inconsistent handling is worth another github-issue but in my case it was just due to the fact that the visitor wanted to process data that should not be processed at all.

I submitted a PR (#31). As this caveat is in a quite central place of that tool please verify accordingly if the assumption and the fix is sane as there's no testsuite yet.

Cheers :)

How do I include meta in my response?

I was able to get it to work with the following:

return array("data"=>$data, "meta"=>array("test"=>50));

However, this was removed from the response when I did so:

{
  "jsonapi": {
    "version": "1.0"
  }
}

and it also added a blank included array (unless I had side loaded objects, then it correctly side loaded them):

{ 
   "included": [],
...
}

Hi,

I'm one of the editors of the JSON API spec and really appreciate your work on this bundle. When it's ready, I'd encourage you to send a PR to json-api/json-api adding to to our implementations page.

Cheers,
Ethan

Hi, I discovered another solution, how could be resolved this problem and it's based on headers. I think that it's much cleaner solution.

The headers Content-Type and Accept will be checked, if contains application/vnd.api+json value, as is described here http://jsonapi.org/format/#content-negotiation, if yes so the entities will be serialized by json api serializer.

And I don't know if it's implemented now, but in this step would be good to implement 415 Unsupported Media Type and 406 Not Acceptable responses on the base of this rules http://jsonapi.org/format/#content-negotiation-servers. Or to create new ticket.

Need to make sure to apply JSON-API related stuff only to mapped objects.

Hi there! Great work with this bundle!

I understand this is still a WIP, but is there a doc (or checklist or reference somewhere in code, or where ever) that specifies which part of the specification is implemented, and what are still pending? It will help people (like me) to understand if we can use it in our projects (I understand that this is still not recommended for production), with an assessment of the risks. Also, this will give visibility to (wannabe) contributors on where they can start contributing, if anyone is interested.

This checklist might also include the status of a particular spec segment like stable, buggy, not implemented.

Just a thought.

When I try to use this on an Entity that inherits from an abstract super class, I cannot get it to use the child class as the resource. It won't work unless I put the Resource decorator on the super class. Any ideas on how to handle this?

Hi Steffen,

you are using the array_filter function with the ARRAY_FILTER_USE_KEY-flag in https://github.com/steffenbrem/JsonApiBundle/blob/master/Serializer/JsonApiSerializationVisitor.php#L246 . The flags was introduced in PHP 5.6. So the the required php version should be updated in the composer file.

Hi,

With the new version 1.8 from friendsofsymfony/rest-bundle the following info is logged:

php.INFO: Support of custom serializer as fos_rest.serializer is deprecated since version 1.8. You should now use FOS\RestBundle\Serializer\Serializer.

The problem is, that the SerializerPass overwrites fos_rest.serializer with json_api_server.serializer and this Serializer does not implement the Serializer interface which is expected from fosrest.

The interface from fosrest is not compatible with the interface used by JMSSerializer (SerializerInterface):
fosrest:
public function serialize($data, $format, $context = null);
public function deserialize($data, $type, $format, $context = null);
vs.
JMSSerializer
public function serialize($data, $format, SerializationContext $context = null)
public function deserialize($data, $type, $format, DeserializationContext $context = null)

Does anyone have an idea how to combine those two in a 'good' way?

Hi,

According to the documentation, there's a property "showRelatedLink", but using this generates the following Error:

[Creation Error] The annotation @jsonapi\Relationship declared on property AppBundle\Entity\PostCollection::$posts does not have a property named "showRelatedLink". Available properties: includeByDefault, showData, showLinkSelf, showLinkRelated

This is a meta issue to gather full Specification of JSON API and to check what is supported/implemented by this library. (Will add more things, any contribution is welcome)

Each checkmark can be converted into a test case as a result.

Server Responsibilities

• Servers MUST send all JSON API data in response documents with the header Content-Type: application/vnd.api+json without any media type parameters.
• Servers MUST respond with a 415 Unsupported Media Type status code if a request specifies the header Content-Type: application/vnd.api+json with any media type parameters.
• Servers MUST respond with a 406 Not Acceptable status code if a request’s Accept header contains the JSON API media type and all instances of that media type are modified with media type parameters.

Document structure

• A JSON object MUST be at the root of every JSON API request and response containing data. This object defines a document’s “top level”.
• A document MUST contain at least one of the following top-level members:
  • data: the document’s “primary data”
  • errors: an array of error objects
  • meta: a meta object that contains non-standard meta-information.
• The members data and errors MUST NOT coexist in the same document.
• A document MAY contain any of these top-level members:
  • jsonapi: an object describing the server’s implementation
  • links: a links object related to the primary data.
  • included: an array of resource objects that are related to the primary data and/or each other (“included resources”).
• If a document does not contain a top-level data key, the included member MUST NOT be present either.
• The top-level links object MAY contain the following members:
  • self: the link that generated the current response document.
  • related: a related resource link when the primary data represents a resource relationship.
  • pagination links for the primary data.
• Primary data MUST be either:
  • a single resource object, a single resource identifier object, or null, for requests that target single resources
  • an array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections
• A logical collection of resources MUST be represented as an array, even if it only contains one item or is empty.

Resource Objects

• A resource object MUST contain at least the following top-level members: id, type
• Exception: The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.
• In addition, a resource object MAY contain any of these top-level members:
  • attributes: an attributes object representing some of the resource’s data.
  • relationships: a relationships object describing relationships between the resource and other JSON API resources.
  • links: a links object containing links related to the resource.
  • meta: a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.

Identification

• Every resource object MUST contain an id member and a type member. The values of the id and type members MUST be strings.
• Within a given API, each resource object’s type and id pair MUST identify a single, unique resource. (The set of URIs controlled by a server, or multiple servers acting as one, constitute an API.)
• The values of type members MUST adhere to the same constraints as member names.

Fields

• Fields for a resource object MUST share a common namespace with each other and with type and id. In other words, a resource can not have an attribute and relationship with the same name, nor can it have an attribute or relationship named type or id.
• The value of the attributes key MUST be an object (an “attributes object”). Members of the attributes object (“attributes”) represent information about the resource object in which it’s defined.
• Complex data structures involving JSON objects and arrays are allowed as attribute values. However, any object that constitutes or is contained in an attribute MUST NOT contain a relationships or links member, as those members are reserved by this specification for future use.
• Although has-one foreign keys (e.g. author_id) are often stored internally alongside other information to be represented in a resource object, these keys SHOULD NOT appear as attributes.

Relationships

• The value of the relationships key MUST be an object (a “relationships object”). Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.
• Relationships may be to-one or to-many.
• A “relationship object” MUST contain at least one of the following:
  • links: a links object containing at least one of the following:
    • self: a link for the relationship itself (a “relationship link”). This link allows the client to directly manipulate the relationship. For example, removing an author through an article’s relationship URL would disconnect the person from the article without deleting the people resource itself. When fetched successfully, this link returns the linkage for the related resources as its primary data. (See Fetching Relationships.)
    • related: a related resource link
  • data: resource linkage
  • meta: a meta object that contains non-standard meta-information about the relationship.
• A relationship object that represents a to-many relationship MAY also contain pagination links under the links member, as described below.

Related Resource Links

• If present, a related resource link MUST reference a valid URL, even if the relationship isn’t currently associated with any target resources.
• Additionally, a related resource link MUST NOT change because its relationship’s content changes.

Resource Linkage

• Resource linkage MUST be represented as one of the following:
  • null for empty to-one relationships.
  • an empty array ([]) for empty to-many relationships.
  • a single resource identifier object for non-empty to-one relationships.
  • an array of resource identifier objects for non-empty to-many relationships.

Resource Links

• The optional links member within each resource object contains links related to the resource. If present, this links object MAY contain a self link that identifies the resource represented by the resource object.
• A server MUST respond to a GET request to the specified URL with a response that includes the resource as the primary data.

Resource Identifier Objects

• A “resource identifier object” MUST contain type and id members.
• A “resource identifier object” MAY also include a meta member, whose value is a meta object that contains non-standard meta-information.

Compound Documents

• In a compound document, all included resources MUST be represented as an array of resource objects in a top-level included member.
• Compound documents require “full linkage”, meaning that every included resource MUST be identified by at least one resource identifier object in the same document. These resource identifier objects could either be primary data or represent resource linkage contained within primary or included resources.
• The only exception to the full linkage requirement is when relationship fields that would otherwise contain linkage data are excluded via sparse fieldsets.
• A compound document MUST NOT include more than one resource object for each type and id pair.

Meta Information

• The value of each meta member MUST be an object (a “meta object”).
• Any members MAY be specified within meta objects.

Links

• The value of each links member MUST be an object (a “links object”).
• Each member of a links object is a “link”. A link MUST be represented as either:
  • a string containing the link’s URL.
  • an object (“link object”) which can contain the following members:
    • href: a string containing the link’s URL.
    • meta: a meta object containing non-standard meta-information about the link.

JSON API Object

• A JSON API document MAY include information about its implementation under a top level jsonapi member.
• The jsonapi object MAY contain a version member whose value is a string indicating the highest JSON API version supported.
• This object MAY also contain a meta member, whose value is a meta object that contains non-standard meta-information.

Member Names

• All member names used in a JSON API document MUST be treated as case sensitive by clients and servers, and they MUST meet all of the following conditions:
  • Member names MUST contain at least one character.
  • Member names MUST contain only the allowed characters listed below.
  • Member names MUST start and end with a “globally allowed character”, as defined below.

Allowed Characters

• Use only allowed characters when generating member names

Fetching Data

• A server MUST support fetching resource data for every URL provided as:
  • a self link as part of the top-level links object
  • a self link as part of a resource-level links object
  • a related link as part of a relationship-level links object

Responses

200 OK

• A server MUST respond to a successful request to fetch an individual resource or resource collection with a 200 OK response.
• A server MUST respond to a successful request to fetch a resource collection with an array of resource objects or an empty array ([]) as the response document’s primary data.
• A server MUST respond to a successful request to fetch an individual resource with a resource object or null provided as the response document’s primary data.
• null is only an appropriate response when the requested URL is one that might correspond to a single resource, but doesn’t currently.

404 Not Found

• A server MUST respond with 404 Not Found when processing a request to fetch a single resource that does not exist, except when the request warrants a 200 OK response with null as the primary data (as described above).
• A server MAY respond with other HTTP status codes.
• A server MAY include error details with error responses.
• A server MUST prepare responses, and a client MUST interpret responses, in accordance with HTTP semantics.

Fetching Relationships

Responses

200 OK

• A server MUST support fetching relationship data for every relationship URL provided as a self link as part of a relationship’s links object.
• The primary data in the response document MUST match the appropriate value for resource linkage, as described above for relationship objects.
• The top-level links object MAY contain self and related links, as described above for relationship objects.

404 Not Found

• A server MUST return 404 Not Found when processing a request to fetch a relationship link URL that does not exist.
• f a relationship link URL exists but the relationship is empty, then 200 OK MUST be returned, as described above.

Inclusion of Related Resources

• An endpoint MAY return resources related to the primary data by default.
• An endpoint MAY also support an include request parameter to allow the client to customize which related resources should be returned.
• If an endpoint does not support the include parameter, it MUST respond with 400 Bad Request to any requests that include it.
• If an endpoint supports the include parameter and a client supplies it, the server MUST NOT include unrequested resource objects in the included section of the compound document.
• The value of the include parameter MUST be a comma-separated (U+002C COMMA, “,”) list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, “.”) list of relationship names.
• If a server is unable to identify a relationship path or does not support inclusion of resources from a path, it MUST respond with 400 Bad Request.

Sparse Fieldsets

• A client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter.
• The value of the fields parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned.
• If a client requests a restricted set of fields for a given resource type, an endpoint MUST NOT include additional fields in resource objects of that type in its response.

Sorting

• A server MAY choose to support requests to sort resource collections according to one or more criteria (“sort fields”).
• An endpoint MAY support requests to sort the primary data with a sort query parameter. The value for sort MUST represent sort fields.
• An endpoint MAY support multiple sort fields by allowing comma-separated (U+002C COMMA, “,”) sort fields. Sort fields SHOULD be applied in the order specified.
• The sort order for each sort field MUST be ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“), in which case it MUST be descending.
• If the server does not support sorting as specified in the query parameter sort, it MUST return 400 Bad Request.
• If sorting is supported by the server and requested by the client via query parameter sort, the server MUST return elements of the top-level data array of the response ordered according to the criteria specified. The server MAY apply default sorting rules to top-level data if request parameter sort is not specified.

Pagination

• A server MAY choose to limit the number of resources returned in a response to a subset (“page”) of the whole set available.
• A server MAY provide links to traverse a paginated data set (“pagination links”).
• Pagination links MUST appear in the links object that corresponds to a collection. To paginate the primary data, supply pagination links in the top-level links object. To paginate an included collection returned in a compound document, supply pagination links in the corresponding links object.
• The following keys MUST be used for pagination links:
  • first: the first page of data
  • last: the last page of data
  • prev: the previous page of data
  • next: the next page of data
• Keys MUST either be omitted or have a null value to indicate that a particular link is unavailable.
• Concepts of order, as expressed in the naming of pagination links, MUST remain consistent with JSON API’s sorting rules.
• The page query parameter is reserved for pagination. Servers and clients SHOULD use this key for pagination operations.

Filtering

• The filter query parameter is reserved for filtering data. Servers and clients SHOULD use this key for filtering operations.

Creating, Updating and Deleting Resources

• A server MAY allow resources of a given type to be created. It MAY also allow existing resources to be modified or deleted.
• A request MUST completely succeed or fail (in a single “transaction”). No partial updates are allowed.

Creating Resources

• A resource can be created by sending a POST request to a URL that represents a collection of resources. The request MUST include a single resource object as primary data. The resource object MUST contain at least a type member.
• If a relationship is provided in the relationships member of the resource object, its value MUST be a relationship object with a data member. The value of this key represents the linkage the new resource is to have.

Client-Generated IDs

• A server MAY accept a client-generated ID along with a request to create a resource. An ID MUST be specified with an id key, the value of which MUST be a universally unique identifier.
• The client SHOULD use a properly generated and formatted UUID as described in RFC 4122 [RFC4122].
• A server MUST return 403 Forbidden in response to an unsupported request to create a resource with a client-generated ID.

Responses

• If a POST request did not include a Client-Generated ID and the requested resource has been created successfully, the server MUST return a 201 Created status code.
• The response SHOULD include a Location header identifying the location of the newly created resource.
• The response MUST also include a document that contains the primary resource created.
• If the resource object returned by the response contains a self key in its links member and a Location header is provided, the value of the self member MUST match the value of the Location header.
• If a request to create a resource has been accepted for processing, but the processing has not been completed by the time the server responds, the server MUST return a 202 Accepted status code.
• If a POST request did include a Client-Generated ID and the requested resource has been created successfully, the server MUST return either a 201 Created status code and response document (as described above) or a 204 No Content status code with no response document.
• A server MAY return 403 Forbidden in response to an unsupported request to create a resource.
• A server MUST return 404 Not Found when processing a request that references a related resource that does not exist.
• A server MUST return 409 Conflict when processing a POST request to create a resource with a client-generated ID that already exists.
• A server MUST return 409 Conflict when processing a POST request in which the resource object’s type is not among the type(s) that constitute the collection represented by the endpoint.
• A server SHOULD include error details and provide enough information to recognize the source of the conflict.
• A server MAY respond with other HTTP status codes.
• A server MAY include error details with error responses.
• A server MUST prepare responses, and a client MUST interpret responses, in accordance with HTTP semantics.

(will add more a bit later....)

The last commit was Jan 22, 2018. Will it be still maintained?

Currently, we can keep track of all the included data, but not for the primary resources stored under data. How can we check if a relationship from an included record is already in the primary data?

The metadata should be cached properly, so that it does not have to resolve it every request.

I inadvertently tried to serialize an entity that wasn't configure for JsonApiBundle correctly and got the message: "Error: Call to a member function getType() on null" on line 334 of JsonEventSubscriber.php.

Once I configured the entity with the correct decorations, it worked.

It'd be nice to have it return some sort of error that is a little more descriptive as to the issue it's encountered. I'd take a stab at a PR, and I'm willing to, but wanted to see if you thought this would be helpful?

What type of strategy would be best for error handling? I'm not exactly sure how to go about it, but I'd be open to trying it if anyone has suggestions on how best to do it.

When a child class (bar) that inherits from a concrete base (foo) class is serialized, the JsonApiBundle resource annotation from the base class is loaded into the cache in place of the child class annotation and the base class annotation is never loaded into its correct class.

 /**
 * @JsonApi\Resource(type="foo")
 */
class foo
{
//...
}

 /**
 * @JsonApi\Resource(type="bar")
 */
class bar extend foo
{
//...
}

Result is that the "foo" will be loaded into the resource annotation for for the bar class instead of "bar".

I previously submitted PR #17 to resolve this in a basic manner for abstract classes, but I'm not sure how to handle the concrete class situation or if my original PR needs a different strategy.

Thanks!

Hi,

I noticed, that you have started using new short array syntax. I think, that we should not use this new syntax, because min. requirements for Symfony 2.x is PHP 5.3.x. But this new syntax is only supported from PHP 5.4.

My opinion is, that we should preserve compatibility with version, which is supported by latest Symfony.

How do you look at this, do you think, that it's OK?

Hello, @koemeet

Could you please clarify which exact license is used for your bundle?

For the full copyright and license information, please view the LICENSE file that was distributed with this source code.

Unfortunately, there no such file is repository source.

Hello,

Since i'm not using domain.tld/api/resource but rather api.domain.tld/resource, I'm running into a problem with the following:
in https://github.com/steffenbrem/JsonApiBundle/blob/master/EventListener/Serializer/JsonEventSubscriber.php#L67 , the baseurl is hard coded as /api with no options to change it, thus making all the generated urls invalid. Wouldn't it be a better approach to use the symfony router to generate these urls dynamically, thus giving the opportunity of a custom URL structure?

I don't want the attribute "hash" to appear in the response.
How can I hide certain properties in the response?
Thank you!

use Mango\Bundle\JsonApiBundle\Configuration\Annotation as JsonApi;

/**
 * @JsonApi\Resource(type="posts")
 */
 class Post 
 {
    /**
     * @JsonApi\Id
     */
    protected $uuid;
    
    /**
     * @JsonApi\Relationship(includeByDefault=true, showLinkSelf=false, showLinkRelated=false)
     */
    protected $comments;

    protected $hash;
 }