8000 Introduce the included extension by somdoron · Pull Request #1472 · json-api/json-api · GitHub
[go: up one dir, main page]
Skip to content

Introduce the included extension #1472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: gh-pages
Choose a base branch
from
Open

Introduce the included extension #1472

wants to merge 1 commit into from

Conversation

somdoron
Copy link
@somdoron somdoron commented May 3, 2020

Provide an alternative to the top-level included member. The advantage of this approach is that it is easier for the consumer of the API to fetch the included data (instead of searching for it in the included member).

The disadvantage is, that a resource may be embedded more than once.

@gabesullice
Copy link
Contributor
gabesullice commented Aug 7, 2020 •
edited
Loading

@somdoron, I think an extension that embeds related resource objects would make many JSON:API users happy.

At this very moment, I don't think we're ready to adopt another extension into jsonapi.org, but that should not stop you from publishing this elsewhere in the interim. We will be making recommendations on jsonapi.org in the coming week about how we think extensions should be publicized and distributed.

As for the content of this extension, it makes me very happy to see the community running with the idea of extensions. I'm glad the namespace language worked for you and that you've incorporated it correctly 👍

I think I would suggest three changes:

  1. Choose a different namespace than included since that already has a specific meaning in the spec. Perhaps embed?
  2. Define a new query parameter instead of altering the processing rules for the existing include query parameter (extensions are not allowed to do this anyway). Perhaps ?embed:related=author?
  3. Instead of adding three new members, why not write the language such that you're embedding the data member of the document linked to by the related link. I think you probably were trying to avoid duplicating type and id, but that's a little silly considering that the extension will probably end up causing lots of duplicated content ;) With that said, you could easily avoid this by saying that the data and embed:data members are mutually exclusive. I.e. if embed:data is present, data should be omitted and vice versa.
{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "embed:data": {
          "type": "people",
          "id": "9",
          "attributes": {
            "firstName": "Dan",
            "lastName": "Gebhardt",
            "twitter": "dgeb"
          },
          "links": {
            "self": "http://example.com/people/9"
          }
        },
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        }
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  },
  "links": {
    "self": "http://example.com/articles/1?embed:related=author"
  }
}

My biggest concern with this extension would be in keeping the the dot-separated relationship syntax of the include query parameter, instead of limiting it to depth 1. The problem of duplicates will get exponentially worse with longer include paths. Implementers will have to be very careful not to write infinite looping code and/or not to exceed memory capacity. A "considerations" section at the bottom of the spec would probably be useful so you can point out implementation pitfalls.

Copy link
Contributor

I'm not convinced there's an issue with having to search included for resources, since a vaguely reasonable client library can make retrieval of relationships consistent.

If something like @gabesullice's embed:data is allowed but not required, duplication can be avoided as well: the first reference to a resource that isn't primary data can use embed:data, and subsequent references can use a resource identifier object. This breaks down a bit for to-many relationships, since data contains a list of resource identifier objects.

@jelhan jelhan added the extension Related to existing and proposed extensions as well as extensions in general label Feb 17, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@auvipy auvipy auvipy approved these changes

Assignees
No one assigned
Labels
extension Related to existing and proposed extensions as well as extensions in general
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@somdoron @gabesullice @freddrake @auvipy @jelhan
0