Potential items for review

[MikeRalphson]

• [x] Make document instances identifiable and versionable, e.g. with a top-level sla4api property containing a semver value (I note that some of the examples have an sla property with a numeric 1.0 value)
• [x] move Specification.md to something like versions/1.0.0-pre.md
• [x] use full text of Apache-2.0 license so GitHub identifies it correctly
• [x] GitHub: fix No description, website, or topics provided.
• [ ] GitHub: add Code of Conduct and issue templates early in the process
• [ ] use open formats for documentation directory
• [ ] define a media-type for SLA instance documents following the vnd.oai. style with +json variant and version property
• [ ] recommend naming of the instance documents (e.g. sla.yaml or sla.json)
• [ ] consider registering an RFC5785 .well_known location
• [ ] include a (cut-down?) contact object so contact information specific to the SLA info is available
• [ ] allow specification extensions (x- properties) within SLA instance documents for extensibility
• [x] update Swagger 2.0 examples to OpenAPI 3.x - should include patch version: e.g. 3.0.3
• [ ] is it appropriate to use floating point number types for currency values (especially for things like BTC)? Suggest integer with divisor or multiplier / units modifier
• [ ] use ISO-8601 for durations
• [ ] set up CI to validate/lint markdown using mdv - no issues currently
• [x] s/quartely/quarterly/g
• [x] s/matric/metric/g
• [x] s/managment/management/g

[MikeRalphson]

Pinging @fmvilas from AsyncAPI and @IvanGoncharov from GraphQL-wg to see if they have input on making this type of document more widely applicable to different kinds of APIs. @kinlane I guess having an extension property in apis.json wouldn't be an issue?

[fmvilas]

Thanks for pinging me, @MikeRalphson. I'll try to find some time to properly review this spec.

PS: It feels incredibly great to see folks from Sevilla working on API specs, especially because I'm from Badajoz :)

[IvanGoncharov]

@MikeRalphson Was traveling to/from GraphQL Summit.

@IvanGoncharov from GraphQL-wg to see if they have input on making this type of document more widely applicable to different kinds of APIs

GraphQL is still used mostly for private APIs and there is only a handful of public APIs. So best practices for SLA is not defined yet at the same time they probably will be different from RESTfull apis.

For example, rate limiting based on the number of requests doesn't make sense for GraphQL since you can send one huge query so providers of GraphQL APIs trying to come with some new approaches like complexity analysis, credit-based limiting or query whitelisting.

So I think it's still too early to formalize SLA for GraphQL APIs and this should be done in ~2-3 years.

[fmvilas]

It's hard to say if this would be useful with messaging APIs. Right now, most of these APIs are internal, so I don't think people could be really interested in SLAs. I predict a raise of public messaging APIs in the next 5 to 10 years, but that's just a bet.

Another way of seeing it is that having an SLA spec might increase the number of people that think about it for messaging APIs. Definitely something to keep an eye on!

[antgamdia]

Thank you all so much for your interest in the SLA4OAI initiative. I've been fixing some typos and adding a full-text license for gh. The next actions will be discussed in the board with @pafmon in order to define a working roadmap. If anyone else is interested in collaborating with this project, ping me and we'll add you to the mailing list.