In the post #32 “SLA from developer’s point of view” I discussed briefly the current SLA practices which are more or less ridiculous. SLA is not defined in machine redable format and practically the only measure is availability “Our SLA is 99.9% monthly”. Absurd! How dare you?!

Apparently the need has been expressed 2014 and new issue was raised 2016. The latter is still open issue. The idea of taking advantage of extensions was mentioned. Furthermore a statement was added to the 1st issue mentioned: “In the future, if specific extensions are commonly used, we may include them inherently in the spec.”

As APIs are gaining notoriety and API marketplaces are increasingly growing, at least two key aspects can be identified: i) ease of use for its potential developers; ii) a flexible usage plan that fits their customer’s demands. The first item has been addressed very widely by producing lots of tools and technical solutions for example around machine readable Swagger/OAS. The second item on the other hand has been neglected or has been pushed to lower priority stack so far.

There is no standard machine readable spec to describe business aspects including SLA for REST APIs. The SLA aspects are implemented at API gateway level and thus all are vendor specific. This in turn creates small (or bigger) vendor lock since API provider needs to redo the configuration (most likely manually) if they change API gateway.

Business decisions affect the dx as well by creating business requirements and limitations which are more often seen in business plans offered. Also the bigger business strategy might bring requirements to individual API level. Thus I’ve added the business aspect to 360 DX pie. SLA affects also marketing. Naturally it is related to customers daily life as part of delivering value to their customers.

Why should it exist?

Here’s a few reasons. Having a standard machine readable standard to describe the configuration/business aspects and SLA would

Imaginery example: I could build a service which tells me which of the SMS sending APIs should I choose. I would tell the service that I have 10 000 emails to send each month and I have 100 euros to use. Which of the APIs in the markets even make this possible? Implementing such as service as CLI tool or web app would be easy if the needed information would be in machine readable format. Now I would need to use screen scraping to collect the information. And as we all know, websites change and that would always break the scraper too. Thus this case would require machine readable SLA specs.

I have gutt feeling that API management, market places and API catalogues are going to merge at some level during the following years. ProgrammableWeb started the game, but more API management including catalogues have emerged. These new catalogues do not just list the APIs and related tools, but also offer management and billing as well. They are platforms. It would also be in the benefit to have all information in standard machinee readable format.

Another thing supporting the idea is the rhetoric of spec file as agreement or contract. So far the discussion has dwelled around the technical aspects eg. does the implementation follow the spec or not. The business aspects should be there as well since API is more and more a product and they have business aspects.

Keep in mind that the secondary customer group for your API are the decision makers and they need to know the cost structure, limitations and opportunities as well. You need to serve them as well as the hardcore application implementing developers.

Extension approach

After digging a little deeper I found two related articles describing machine readable SLA extension to Open API spec. The first one describes the basics “Fostering SLA-Driven API Specifications (2018)” and the second one the SLA driven gateway solution “Governify for APIs: SLA-Driven Ecosystem for API Governance (2019)”. The spec for OAS SLA extension with examples is also on Github.

To me this is one of the signs that APIs are not fully treated as products. Yes, the technical nature of API is machine readable but the business aspects of it are not. I started with technical approach to APIs but working with API management solutions opened my eyes to other aspects of the APIs. Lately my focus has turned towards business and naturally DX aspects.

Existing standardisation efforts

Currently the definition of SLA standards has been an active field of research, but the outcomes are still indeterminate. Interesting results are available for SLA representation (e.g., WSAgreement, WSLA), and as concerns tools/environments for their management (e.g., SLA@SOI, WSAG4J).

A more advanced state of SLA standardization is offered by ISO 19086, which proposes a clear standard for SLAs in cloud. The above cited standard introduces the main concepts related to SLA, and examples of guarantees that can be offered. However, their description is very general and leads more to SLAs written in natural language than to the adoption of automated SLA systems which would require easy to apply machine readbale specs. The API world has started to use REST more than SOAP, and thus we would need similar machine readable SLA spec standard as WSLA is for SOAP APIs. I must admit that I have never really worked with SOAP APIs, I jumped directly to REST APIs and later to other approaches.

What the machine readable SLA for REST could be?

The researchers have labelled first candidate solution as iAgree Specification. The mentioned articles list following themes to be included in SLA:

Researchers combined the OAS and iAgree specification and SLA4OAI was born. Here’s an example from the article how those look as YAML

Usage would be to define an SLA-driven OAS as an OAS document which has been extended with an optional attribute, x-sla,with a URI pointing to the JSON or a YAML document that contains different sections.

swagger: '2.0'
info:
  version: '1.0.0'
  title: Swagger Petstore (Simple)
  description: A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification
  termsOfService: http://helloreverb.com/terms/
  x-sla: ./petstore-sla.yml
  contact:
    name: Swagger API team
    email: foo@example.com
    url: http://swagger.io
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
host: petstore.swagger.io
basePath: /api
schemes:

The SLA spec consists of multiple files to define aspects of the SLA:

The pattern how for example ratelimiting has been defined in to SLA4OAI follows the structure of OAS

quotas:
  /pets:
    get:
      requests:
        - max: 20
          period: minutely
          scope: account
        - max: 100
          period: hourly
          scope: tenant
    post:
      requests:
        - max: 100
          period: minutely
      resourceInstances:
        - max: 500
      animalTypes:
        - max: 5
rates:
  /pets/{id}:
    get:
      requests:
        - max: 3
          period: secondly
guarantees:
  global:
    global:
      - objective: responseTimeMs <= 250
        period: daily
        window: dynamic

It looks like the idea could be injected to OAS standard pretty easily. As it is used as an extension some parts of the information are duplicates. The guarantees looks like root level definition. In OAS spec your data models would be defined similarly at the root level. Of course bundling all the aspects of SLA to OAS would require more thinking and discussion.

Complete simple example can be found from Github, https://github.com/isa-group/SLA4OAI-Specification/tree/master/samples/petstore

Call for last message

Since the 100 Days DX series is about to end, I’m asking all developers to provide opinions on two things. Reply to the tweet (image is link):

Some more to read from 100 Days DX