Skip to content
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.

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

Introduce describedby link relation #1447

Merged
merged 2 commits into from Jan 8, 2020
Merged

Introduce describedby link relation #1447

merged 2 commits into from Jan 8, 2020

Conversation

dgeb
Copy link
Member

@dgeb dgeb commented Dec 3, 2019

The describedby link relation can be used to identify a description document, which may be an OpenAPI definition, a JSON Schema document, or another description format.

It's proposed that the describedby member can appear in two places:

  • A) in the top-level links object, in which case it provides a description for the current document.
  • B) inside any link object, in which case it provides a description for the target of the link.

We could optionally allow this member inside any links object that can also contain a self link - namely, resource links and relationship links. This would be consistent with (A) but also somewhat redundant with (B). I'd like to make a decision about this explicitly prior to merging.

Another question is whether there should be a central definition of a "description document" within the JSON:API spec, or whether using parenthetical examples (e.g. OpenAPI or JSON Schema) is sufficient.

related: #1281

/cc @philsturgeon @gabesullice

@dgeb dgeb mentioned this pull request Dec 3, 2019
@philsturgeon
Copy link

philsturgeon commented Dec 3, 2019

🚢 👍

@jugaadi
Copy link

jugaadi commented Dec 4, 2019

Thanks @dgeb @philsturgeon @gabesullice for initiating this effort.

I'd vote for adopting a central default description format to avoid any confusion between API providers and consumers. Any other format can be handled through profiles.

In this case, I would prefer OpenAPI because:

  1. Large community
  2. Industry wide support
  3. Tooling
  4. Alignment with JSON Schema

PS: We are already using OpenAPI for describing JSON:API resources. This spec is used by both the client and server to handle requests and responses.

@dgeb
Copy link
Member Author

dgeb commented Dec 11, 2019

@jugaadi Thanks for your feedback! I agree that OpenAPI is a solid choice and a good starting point.

While we don't want to restrict the content type of the description documents pointed to by describedby, we definitely want to provide some recommendations in the non-normative section of the site that will cover best practices. We can include example usage of OpenAPI and JSON Schema to start, and would appreciate your contributions to the recommendations based on your experience.

@dgeb dgeb requested a review from gabesullice Dec 11, 2019
@dgeb
Copy link
Member Author

dgeb commented Dec 11, 2019

@gabesullice I think this is ready to review. Please let me know what you think about my question from the PR description:

We could optionally allow this member inside any links object that can also contain a self link - namely, resource links and relationship links. This would be consistent with (A) but also somewhat redundant with (B). I'd like to make a decision about this explicitly prior to merging.

@gabesullice
Copy link
Contributor

gabesullice commented Jan 8, 2020

@dgeb and I discussed this today. WRT to the question in the description, we decided against allowing describedby links in resource or relationship objects because it may cause confusion about whether the description document is intended to describe the object as it appears in the current response or the description document of the document you expect to receive by following its self link. The describedby target attribute is a link hint that clearly indicates that the description document it targets describes the target URL.

I think this PR is ready to merge.

Copy link
Contributor

@gabesullice gabesullice left a comment

This looks good to me.

@dgeb dgeb merged commit cac493b into gh-pages Jan 8, 2020
@dgeb dgeb deleted the describedby branch Jan 8, 2020
@evert
Copy link

evert commented Jan 8, 2020

There is also this format: https://tools.ietf.org/html/draft-nottingham-link-hint

bit different from how this was done, but does the same thing nonetheless

@gabesullice
Copy link
Contributor

gabesullice commented Jan 8, 2020

@evert, afaict, we could integrate that RFC w/ JSON:API fairly easily. They're not mutually exclusive. To do that, we would add hints as an allowed member of a link objects both as a sibling of—and similar to—the params member.

If you're saying that we could have added describedby under hints, I don't think that works because that RFC is about providing hints related to HTTP headers, statuses, etc. I suppose it would be a proxy for the Link header, but for better or for worse the JSON:API spec, talks about links exclusively about links represented in the JSON response body.

Perhaps you're referring to the links hint from that RFC since we could have done something like:

links: {
  self: {
    href: /articles/1,
    hints: {
      links: {
        describedby: /schemas/article.json
      }
    }
}

Instead of what we chose:

links: {
  self: {
    href: /articles/1,
    describedby: {
      href: /schemas/article.json
    }
}

We considered something like that (i.e. adding a links target attribute to link objects themselves) but decided against it to keep nesting/complexity to a minimum.

PS. It's funny you mentioned that RFC, I just mentioned it in a post within 30 minutes of your reply 😺

@evert
Copy link

evert commented Jan 8, 2020

Yea just for context, I do believe that your use-case is one of the things link-hints hopes to solve, but it would indeed be a deeper nested structure.

I believe the equivalent syntax would actually be:

links: {
  self: {
    href: /articles/1,
    hints: {
      formats: {
        'application/vnd+api.json': {
           links: {
             describedby: {
               href: "/schemas/article.json",
               type: "application/schema+json"
           }
        }
      }
    }
}

This makes the most sense for links that are explicitly not self links. For a self link, I would just take the format information and lift it to its own link:

links: {
  self: {
    href: /articles/1,
  },
  describedby: {
    href: "/schemas/article.json",
    type: "application/schema+json"
  }
}

@gabesullice
Copy link
Contributor

gabesullice commented Jan 8, 2020

Whoaaa, I had not grokked that bit of the RFC. That's a very thought provoking idea... It's interesting how the format is specialized by a schema/profile.

For a self link, I would just take the format information and lift it to its own link:

This PR does exactly that, but only for top-level links.

@MikeRalphson
Copy link

MikeRalphson commented Aug 26, 2020

Probably not worth opening a new issue, but just thought I'd note that link describedBy is generally about describing a resource (so JSON Schema fits well here), but an OpenAPI document generally describes the surface area of a whole or partial API.

The link rel service-desc might be more appropriate for OpenAPI?

@gabesullice
Copy link
Contributor

gabesullice commented Aug 26, 2020

I expect implementors to link to the HTML representations of their OpenAPI spec where they can add a fragment to the URL. For example, https://petstore.swagger.io/#/user

@claudenirmf
Copy link

claudenirmf commented May 9, 2021

Hello, all! I am facing an interesting situation (not unlike the previous comment from @gabesullice) that could provide some insight.

In our implementation, we want to enhance the experience of developers, mainly because they may have to communicate to similar servers implementing different sets of features (e.g., only some implement a certain filter). So, we have decided to respond to errors with an error object, where we wish to use the link describedby to point to a resource where the developer may learn the specifics of that server's implementation.

Here are the catches: (i) this is intended to be human-readable; (ii) this usually is not even about resource itself, but the parameters sent in the request.

We still want to use describedby in successful responses such that a software can retrieve the JSON Schema for those resources, for instance. But I am unsure about how to differentiate these distinct usages describedby.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants