Feature suggestion: "Backlinks" - Links defined the inverse of the way they are currently
See original GitHub issueI 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:
paths:
/users:
post:
responses:
'201':
links:
GetUserByUserId: # <---- arbitrary name for the link
operationId: getUser
# or
# operationRef: '#/paths/~1users~1{userId}/get'
parameters:
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.
Issue Analytics
- State:
- Created 3 years ago
- Reactions:4
- Comments:8
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.
Documentation
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
Design/Architecture
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.
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.