Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Feature suggestion: "Backlinks" - Links defined the inverse of the way they are currently

See original GitHub issue

I would like the be able to define Links, but in the inverse of the way Links are currently implemented.

Take the example from the docs:

            GetUserByUserId:   # <---- arbitrary name for the link
              operationId: getUser
              # or
              # operationRef: '#/paths/~1users~1{userId}/get'
                userId: '$response.body#/id'
              description: >
                The `id` value returned in the response can be used as
                the `userId` parameter in `GET /users/{userId}`.

If you imagine a system of microservices with many interlinked API schemas… There are going to be dozens of other endpoints in different services which can make use of the userId that results from the POST /users operation. Some of these services will be maintained by different teams, and their API schemas will be in a separate repos etc.

In that context it feels to me quite “back to front” to collect all of these links under the POST /users operation responses, and that instead it would make more sense to define the link on the other side of the relation.

For example on the GET /users/{userId} operation, it would be awesome to have a way to specify that {userId} can be obtained from #/paths/~1users~1/post/responses/201/content/id.

(Possibly as an extension to the Parameters? it would also be useful to be able to set fields in the request body this way, as suggested here ).

In these cases it would be much easier to maintain if the “consumer” API specifies where to get its prerequisites from, rather than having the “producer” API try to list all of the places its data can potentially be used, which is what the Links feature provides currently.

possibly related: #2122 #1594 #1593

Issue Analytics

  • State:open
  • Created 3 years ago
  • Reactions:4
  • Comments:8

github_iconTop GitHub Comments

luckybroman5commented, Feb 23, 2021

After applying OAS extensively towards many different applications, like AWS API Gateway, client generation, documentation, design, and many other things, I MUST request that this be brought to the forefront of discussion for the TSC.

Of the many proposals around this topic, any would do. I don’t think the problem is the how, it’s the why. Therefore rather than being noise amongst the other great proposals on this thread, I will advocate for why this is a paramount need for OAS.


Every set of backend services, whether micro or monolithic, has operations dependent upon responses from the others. It’s almost safe to say, that for documentation purposes, if there are no fragments of a request body that aren’t from another operation’s response body, the two requests don’t belong in the same spec because they’d have nothing to do with each other.

It’s a common process for any type of modeling tool to granularly define relationships. Whether it be an ERD or a Function Call Graph, there needs to be a way for description.

Further, it’s often ambiguous whether identically named parameters are in fact the same or sourced from other responses without explicit declaration. For one to make assumptions about parameters based off name in a large OAS inevitably leads to bugs.

Common, Practical Use Cases

  1. Refresh tokens
    • Typically are returned along with an authentication token and expiration date. The refresh token is then used along with other parameters in the request body to facilitate the “refresh”. Examples: The Github API (Login) -> The Github API (Refresh), at the time of this writing, it’s impossible to represent this common pattern in OAS
  2. Bookmarking Video Content
    • Imagine you provide a video streaming platform and want to allow users to partially watch content, then resume playing later. To achieve this at a basic level, you’ll need to provide some form of identifier for the video, the user’s authentication information, and the playhead. A reasonable place to put the playhead and video Id would be the request body. You’d need to get the video Id from some other meta-data based service.
  3. Compare and Swap
    • If you need to update a resource that could potentially be getting updated by multiple users at the same time, a simple method would be to “Compare and Swap”. If at first you must read from an endpoint to get it’s “compare” value, then how would you include it along with it’s “swap” value in the request body?


Hardly ever do entire request bodies comprise of a singular response attribute. In fact, if this were the case, one could argue that it’s almost certainly flawed API Design. If an entire request body is to be sourced from a response body, why wouldn’t the original operation that returned said response not just make the request on the client’s behalf? The current implementation of having: responseBody encourages an anti pattern, and goes against modern paradigms. Should a developer who doesn’t know better try to design an API completely using OAS, they might be mislead.

The Future and Beyond

The OAS and what it aims to do are truly something great. Using OAS it’s possible to document web request for both the human and machine. One of the last things missing is the ability to further describe the relationships each operation might play into another. Should this “last mile” problem be solved, developers integrating with API’s might not ever need to even write a line of code nor converse with it’s maintainers.

@darrelmiller, @whitlockjc, @earth2marsh, @MikeRalphson, @webron, @usarid, Please do consider/reconsider this enhancement during your next TSC.

tomgreen98commented, Aug 21, 2020

This is exactly what Im looking for. We need to start at an api and work our way back through a list of dependencies setting up everything so we can then run the api we started with.

Read more comments on GitHub >

github_iconTop Results From Across the Web

What Are SEO Backlinks? - Mailchimp
Links on websites other than your own that go back to a page on your website. Backlinks are also called inbound links because...
Read more >
Outbound Links: Do They Affect SEO? - SEMrush
There is an age-old myth in SEO that linking out may harm your website's search engine rankings by diluting your site's PageRank. This...
Read more >
What are Backlinks? And How to Build Them in 2021 - Backlinko
Backlinks (also known as “inbound links”, “incoming links” or “one way links”) are links from one website to a page on another website....
Read more >
Google's PageRank Algorithm: Explained and Tested
But as SEOs are good at reading between the lines, they keep considering PageRank a strong ranking signal and grow backlinks all the...
Read more >
How to use bi-directional links (backlinks) in Notion - Ness Labs
Notion finally launched a popular feature request: bi-directional links, which they call backlinks. While it may seem like a simple addition, it may ......
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found