supporting standard link relations #70
Comments
|
Yes! This is the path I'd like to go for a next major revision. Thank you. Adding to road map. |
|
On 2017-07-31 18:54, Kin Lane wrote:
Yes! This is the path I'd like to go for a next major revision. Thank
you. Adding to road map.
the interesting thing is to figure out how properties/extensions are
done, and that would probably have to go into the processing model for
the format. just through link relations? (probably too limited.) just
through property names? (might have to make clear somehow that some
properties are reflecting link relations.) a mix of property names and
link relations? (then maybe there should be a way of telling whether an
extension is just a property name and when it refers to an existing link
relation.)
|
|
right now the link property "types" supported are: Swagger, RAML, Blueprint, WADL,WSDL, TermsOfService, InterfaceLicense, StatusPage, Pricing, Forums, AlertsTwitterHandle I have numerous others identified across the profiling of APIs I've done - http://theapistack.com/channel-types/ My goal is to create a coherent set of "essential", and standardize model for their relations by version 2.0. I envision many machine readable formats to describe API operations living in harmony with many human readable ones. We'll see how I do. |
|
API Commons was the first attempt to establish machine readable "type" for API licensing. I want to include SDK, and data licensing in next iteration - http://apicommons.org/ |
|
I've done a lot of work to define another separate "type" schema for pricing - http://plans.apievangelist.com/2016/02/13/my-tooling-and-api-for-gathering-and-organizing-the-details-of-the-plans-and-pricing-for-apis/ My goal is to tackle licensing, terms of service, service level agreements, and plans in next five years. ;-) |
|
On 2017-08-01 11:11, Kin Lane wrote:
right now the link property "types" supported are: Swagger, RAML,
Blueprint, WADL,WSDL, TermsOfService, InterfaceLicense, StatusPage,
Pricing, Forums, AlertsTwitterHandle
for some of these i would expect them to be grouped under
"service-description"
(https://tools.ietf.org/html/draft-wilde-service-link-rel#section-4.2)
and then differentiated by media type. after all, it seems that
"Swagger, RAML, Blueprint, WADL, WSDL" are pretty much all the same
general thing, just done a bit differently.
license could be covered by https://tools.ietf.org/html/rfc4946
ToS could be covered by https://tools.ietf.org/html/rfc6903#section-5
status could be covered by
https://tools.ietf.org/html/draft-wilde-service-link-rel#section-5
|
|
Exactly the guidance I need sir! Processing, and will add to the road map. |
|
On 2017-08-01 11:12, Kin Lane wrote:
API Commons was the first attempt to establish machine readable "type"
for API licensing. I want to include SDK, and data licensing in next
iteration - http://apicommons.org/
but license could be covered by https://tools.ietf.org/html/rfc4946 and
then API commons would just be one possible media type representing a
license, right? no need to tightly couple a specific format here.
|
|
On 2017-08-01 11:15, Kin Lane wrote:
I've done a lot of work to define another separate "type" schema for
pricing -
http://plans.apievangelist.com/2016/02/13/my-tooling-and-api-for-gathering-and-organizing-the-details-of-the-plans-and-pricing-for-apis/
the numbers of papers i have read about people formalizing pricing
models. mostly semwebbers hoping for completely automated
substitutability of APIs and needing a complete machine-readable pricing
model for this. i don't think there ever will be such a thing (show me
one and i'll trivially come up with a pricing model you cannot
represent), but i don't want to dissuade anybody from trying... ;-)
|
|
Think that fits. API Commons was a response to Oracle v Google, needs significant realignment. |
|
On 2017-08-01 11:27, Kin Lane wrote:
Exactly the guidance I need sir! Processing, and will add to the road map.
as usual, glad to be of service!
|
|
You know I actually agree with you on pricing. But I can't help but try every couple of years. Some of the more commodity based ones are easy (sms, payments, etc). Think its doable. Second ray of hope is people just seem to copy what they see on this front. If there was common set of blueprints, I'm pretty confident people would use. My pricing guides have always sold well....people are starving for information and patterns. |
|
On 2017-08-01 11:32, Kin Lane wrote:
You know I actually agree with you on pricing. But I can't help but try
every couple of years. Some of the more commodity based ones are easy
(sms, payments, etc). Think its doable.
yes, simplified models are doable. but these are descriptive of what's
going on in the world, they define the things the world can do. very
different thing.
Second ray of hope is people just seem to copy what they see on this
front. If there was common set of blueprints, I'm pretty confident
people would use. My pricing guides have always sold well....people are
starving for information and patterns.
https://tools.ietf.org/html/rfc5988#section-6.2.2 has a mysterious
"payment" link relation type that @mnot put in there but it seems to
have neither a definition document nor a lot of guidance and usage.
but the point is: this link relation (or newly minted one) could be used
to link to pricing models, which then would be identified by media type
and there could be multiple ones and once again these two concerns (API
metadata and the specific pricing model used by the API) would be nicely
separated.
|
|
I would like to propose that APIs.json APIs humanURL evolves to become service-doc (4.1. The service-doc Link Relation Type) - The "service-doc" link relation type is used to represent the fact that a resource is part of a bigger set of resources that are documented at a specific URI. The target resource is expected to provide documentation that is primarily intended for human consumption. I'd like to add 4.2. The service-desc Link Relation Type The "service-desc" link relation type is used to represent the fact that a resource is part of a bigger set of resources that are described at a specific URI. The target resource is expected to provide a service description that is primarily intended for machine consumption. In many cases, it is provided in a representation that is consumed by tools, code libraries, or similar components. -- consolidating swagger, and other macine readable types into a first class service-desc link for each API. |
|
I'd love to hear other folks thoughts on JSON Home's notion of the hint vs link relation. I like the notion of hints, some seem technical, while others more human. |
|
On 2017-08-05 13:16, Kin Lane wrote:
I would like to propose that APIs.json APIs humanURL evolves to become
service-doc (4.1. The service-doc Link Relation Type) - The
"service-doc" link relation type is used to represent the fact that a
resource is part of a bigger set of resources that are documented at a
specific URI. The target resource is expected to provide documentation
that is primarily intended for human consumption.
I'd like to add 4.2. The service-desc Link Relation Type The
"service-desc" link relation type is used to represent the fact that a
resource is part of a bigger set of resources that are described at a
specific URI. The target resource is expected to provide a service
description that is primarily intended for machine consumption. In many
cases, it is provided in a representation that is consumed by tools,
code libraries, or similar components. -- consolidating swagger, and
other macine readable types into a first class service-desc link for
each API.
i like the idea of reusing link relation, but of course i am biased here
because these link relations are proposed by a draft i wrote:
https://tools.ietf.org/html/draft-wilde-service-link-rel
but i'd like to raise a design issue about this: instead of defining
these things one a one-off basis (there is a field service-doc that
happens to coincide with the link relation of the same name), an
alternative approach would be to explicitly allow the use of link
relations. thisbis the approach we take in serv-meta:
https://github.com/dret/servmeta/blob/master/format.md#link-properties
the advantage of this approach is that it (a) makes it clear that the
semantics are the ones defined by the link relation type, and (b) it
dies not require the "host" format to do anything other than have a
generic linking facility.
the challenge is to prevent the "host" format from adding properties
that might be already covered by existing link relations. that's where
serv-meta goes the registry way and assumes that a bit of review process
might help to avoid (most of) these cases.
https://github.com/dret/servmeta/blob/master/format.md#the-servmeta-registry
|
is there a way APIs.json can support RFC 5988 link relations, so that the things it links to can be typed by reusable link relationship type identifiers?
baseURLandhumanURLlook a lot like the proposed link relationsservice-descandservice-doc, for example: https://tools.ietf.org/html/draft-wilde-service-link-relThe text was updated successfully, but these errors were encountered: