Uploaded image for project: ' AGL Development'
  1. AGL Development
  2. SPEC-1903

Investigate and chose an API description format




      On AGL side, we have the following requirements about API description (non exhaustive list):

      • the API specification may be defined by one person
      • then it can be implemented and amended by another person [the developer]
      • some other people from QA would also leverage the API description to write/execute some
        automated tests (test the verbs calls with good values, bad values etc. and
        check the results)
      • some technical information could also be used at runtime (APIs dependencies for example)
      • and at the end, we want also everybody to be able to document the API in the same
        file. Typically, we expect a description of each API verb with its parameters,
        and the detailed description of the responses (fields, meaning, error cases etc.)

      Some background info on the topic:
      The beginning of the presentation shows the history for specifying (web)
      APIs. It started by WSDL, then RAML appeared, then Swagger, openAPI etc.

      One special thing about the APIs in AGL: the bindings are independent of the
      transport mechanism (handled by the binder). So sending a request is just
      sending a json object over the wire and get a json result back (whatever the
      wire is).

      On the other hand, most of the formats we found until recently are related to REST APIs, used
      on the web and don't exactly match what we do with bindings: the APIs
      description are not independent of the transport. Even openAPI 3.0 which handles
      "server messages" (=messages pushed from a webserver to a client through a
      websocket) doesn't represent exactly what we do with events in bindings.

      We also discovered the emerging specification AsyncAPI 1.2 which is more focused
      on messages and doesn't care about the transport. So it's closer to what we do
      in AGL but this deserves more investigation to see if it can be used or not.

      As a summary, we have at least 2 modern specifications to investigate deeper: openAPI and


      Some background articles on asyncAPI:

      Sample generated docsite:


        No reviews matched the request. Check your Options in the drop-down menu of this sections header.



            Riku.Nomoto Riku Nomoto
            sdesneux St├ęphane Desneux
            0 Vote for this issue
            13 Start watching this issue