supporting standard link relations

[dret]

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? baseURL and humanURL look a lot like the proposed link relations service-desc and service-doc, for example: https://tools.ietf.org/html/draft-wilde-service-link-rel

[kinlane]

Yes! This is the path I'd like to go for a next major revision. Thank you. Adding to road map.

[dret]

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.)

[kinlane]

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.

[kinlane]

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/

[kinlane]

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. ;-)

[dret]

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

[kinlane]

Exactly the guidance I need sir! Processing, and will add to the road map.

[dret]

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.

[dret]

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... ;-)

[kinlane]

Think that fits. API Commons was a response to Oracle v Google, needs significant realignment.

[dret]

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!

[kinlane]

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.

[dret]

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.

[kinlane]

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.