Linking API to OpenAPI and documentation

[dret]

would it make sense to recommend best practices for how an API should make its OpenAPI description (and potentially additional documentation) discoverable? we don't know how exactly an API is designed, but if it uses/supports hypermedia, we could recommend to use the link relations proposed here: https://tools.ietf.org/html/draft-wilde-service-link-rel
we might add text such as:

• If an API wants to make its OAI description discoverable from the API itself, it is recommended to use the "service-desc" link relation.
• If an API wants to make its external documentation discoverable from the API itself (the documentation that may be linked from the OpenAPI object via the "externalDocs" field), it is recommended to use the "service-doc" link relation.

i'd be more than happy to make a PR to that effect, but first wanted to raise an issue and discuss it.

[eskoviak]

I think this would be an excellent feature. I have an use case in mind wherein having this sort of resource would be useful.

[darrelmiller]

@dret We've discussed the use of described-by before to link an API to an OpenAPI description. Do you see service-desc as being more suited for this scenario?

[dret]

On 2016-07-04 15:58, Darrel wrote:

@dret https://github.com/dret We've discussed the use of described-by
before to link an API to an OpenAPI description. Do you see service-desc
as being more suited for this scenario?

i am certainly biased because i have cooked up the "service-desc" and
"service-doc" link relation types myself for exactly this kind of scenario.

"described-by" seems a bit odd to me in this case because it seems to be
used mostly for cases where the "described-by" resource is metadata
about the linking resource, such as who authored it, when, and these
kinds of things. but the specification itself is so broad that with
enough willingness, "described-by" is almost the only link relation you'll
ever need on the web:

"The relationship A describedby B asserts that resource B provides a
description of resource A. There are no constraints on the format or
representation of either A or B, neither are there any further
constraints on either resource."

in the end, all the link relation types have fuzzy definitions that
invite a variety of interpretations. but i don't think "described-by"
would be a great fit, because that might better be used to link to a
resource with specific metadata about the linking resource.

[dret]

On 2016-07-04 13:03, Ed Skoviak wrote:

I think this would be an excellent feature. I have an use case in mind
wherein having this sort of resource would be useful.

strictly speaking this would just be a best practice and not an actual
feature that the spec could or should define. but it could be something
to make this aspect of connectedness of resources on the web a bit
better than it is today.

[ePaul]

@darrelmiller I agree with @dret here – describedby seems to be more about a description of the resource content, not of the API (i.e. the resource format/syntax/...).

[dret]

only positive feedback so far. i take that as a form on encouragement. ;-)

[wparad]

So, I think this is a weird request. Something like, because of the use of hypermedia, you would never need to know what all the API's look like, just the ones which are related to the current resource. I like there was an earlier issue requesting the OPTIONS method for the base url to return the document, that seemed like the best idea, it really only needs to be in a place where a person can get it. It would probably end up problematic for this sort of thing to turn into the wsdl.

[dret]

On 2016-07-05 18:34, Warren Parad wrote:

So, I think this is a weird request. Something like, |because of the use
of hypermedia, you would never need to know what all the API's look
like, just the ones which are related to the current resource|.

could you elaborate a bit? i don't think i quite get what you're saying
and what you find weird about the issue. the issue is about how to link
to an OpenAPI description, in case you want to do this. if you don't
want to do this, then that's fine as well.

I like
there was an earlier issue requesting the |OPTIONS| method for the base
url to return the document, that seemed like the best idea, it really
only needs to be in a place where a person can get it. It would probably
end up problematic for this sort of thing to turn into the wsdl.

again, please elaborate on that a little bit. what's the connection
between interlinking resources and WSDL?

[wparad]

@dret, you bring up some interesting points. Most noteworthy I would add though is fundamentally hypermedia provides the mechanism for self-discoverable APIs. I have found Google's similar thing with instructions, but I tempted to believe that this documention should be available from a human readable source, a wiki, developer docs, etc... What would be the use case to have something like this?

[dret]

On 2016-07-05 20:10, Warren Parad wrote:

@dret https://github.com/dret, you bring up some interesting points.
Most noteworthy I would add though is fundamentally hypermedia provides
the mechanism for self-discoverable APIs. I have found Google's similar
thing https://www.googleapis.com/discovery/v1/apis with instructions
https://developers.google.com/discovery/v1/reference/apis, but I
tempted to believe that this documention should be available from a
human readable source, a wiki, developer docs, etc... What would be the
use case to have something like this?

to have something like what? do you mean the links that i propose in
that issue? it makes the service description and service documentation
discoverable from a resource via standardized/recommended means.

i am afraid i still don't quite understand your concerns. are you
concerned about making description/documentation discoverable as
proposed in this issue, or concerned about the specifics how it is proposed?

[wparad]

Aren't full APIs discoverable from their documentation, I.e. your service wiki or client homepage/portal. Is that not what service owners are doing? Are some teams doing something that makes no sense?

[dret]

On Jul 6, 2016, at 20:25, Warren Parad notifications@github.com wrote:

Aren't full APIs discoverable from their documentation, I.e. your service wiki or client homepage/portal. Is that not what service owners are doing? Are some teams doing something that makes no sense?

i don't know the answer to that question. but i don't think it matters for this issue. this issue is about how to discover service description/documentation from resources, not the other way around.

[wparad]

Isn't the recommendation is always use link relations where appropriate? Especially type and self, others as it makes sense. I'm not sure how useful the ones in the rfc you created are, although I suppose someone could find a use, but either way, why call them out in the Open API specification?

[darrelmiller]

@wparad What @dret is suggesting is to use link relations. That what service-desc and service-doc are. The important part is that they bring meaningful semantics to an embeded URL. Obviously, you can chose not to use them, but I see value in OpenAPI making a recommendation regarding the appropriate link relation type identifier that can be used to discover the spec. It's definitely better than our current reliance on a well known filename.

[dret]

On 2016-07-07 21:04, Warren Parad wrote:

Isn't the recommendation is always use link relations where appropriate?
Especially type and self, others as it makes sense. I'm not sure how
useful the ones in the rfc you created are, although I suppose someone
could find a use, but either way, why call them out in the Open API
specification?

the proposal of this issue is to recommend to make OpenAPI descriptions
discoverable. the issue proposes to do that using specific link relation
types. do you object against making Open API descriptions discoverable,
or against using the proposed link relation types?