Investigate and chose an API description format

Re-opened and assigned to Production Readiness Epic. Assigned to  for now. Eventually should be assigned to someone in the App FW EG.  During the App FW Eg meeting this week we discussed a few possible solutions. 

Just for the record as this was mentoned during the Berlin F2F meetings: 'afbidl' stands for 'Application Framework/Binder Interface Description Language'.

Status updated, posted on the mailing list (https://lists.linuxfoundation.org/pipermail/automotive-discussions/2019-July/007524.html)

There's an ongoing task to specify an API schema (see SAT meeting minutes back
in November 2018 [1] as well as [2])

Back in 2018, some people at IoT.bzh investigated on API specification formats
(openAPI, asyncAPI ... and other IDLs). The conclusion at that time was that
none of the existing formats has the required features: some are too
web-centric, others not fitted for describing unattended events, some others too
complex = not human readable/writable.

So we decided to create a specific schema 'afbidl' that fits with the concept of
AGL bindings and covers all the features we need:

• written in readable YAML or JSON (YAML for human, JSON for machines)

• describe APIs in details: verbs, events, datatypes, unit tests + expected
  results ... leveraging JsonSchema spec (https://json-schema.org/)

• having an online editor should be pretty easy (we could imagine something
  close to [3])

• generators can read the API description and produce various outputs:

• code skeleton / stubs

• API tests for QA

• API compliance information (test if a binding complies with the API using
  introspection)

• documentation (markdown for doc site, HTML for local usage, text, pdf ...)

• ...

For the documentation part, the format we propose includes the "book schema"

already used in repositories to describe the available documentation (example
here[4]).

We took the simple GPS API to show what it would look like: see [5] for the API
description and [6] for some generated HTML (formatting is missing).

[1]:https://wiki.automotivelinux.org/agl-sat-meetings#november_22_2018
[2]:https://lf-automotivelinux.atlassian.net/browse/SPEC-1903
[3]:http://editor.asyncapi.org/
[4]:https://git.automotivelinux.org/apps/agl-service-can-low-level/tree/docs/api-services-book.yml
[5]:https://git.automotivelinux.org/apps/agl-service-gps/tree/api/gps-service-geolocation.yml?h=sandbox/benierc/newapis
[6]:https://iot.bzh/download/public/tmp/gps-service-geolocation.html

Quote of Documentation meeting notes (November 14th 2018) sent by

• AsyncAPI 1.2: Stephane studied openAPI and asyncAPI. But none really fits our needs:
  openAPI is too web-oriented and asyncAPI only focuses on messages (which is a
  part of what we're doing). What we do with binders/bindings is in between both.

So we'll propose a new description format: the name for this new format is not
decided yet (proposals are welcome)... Let's call it "AglAPI" for now:

• Intuitive description of an AGL API by a human writer (JSON format supported,
  YAML format may be optionally), close to what is developed in a binding: we call
  'verbs', we get 'responses', we send 'events'... That's the vocabulary we use
  every day: let's adopt it for API description, so people are not lost.

• API documentation (metadata available, i18n support in a second phase)

• Parameters/objects description using JSONschema, very close to what openAPI does

• QA tests description for verbs/events (generate automated QA)

• Support for permissions

• It should be possible to translate an 'AglAPI' file into an openAPI file.

• Similarly, we could probably import existing APIs from openAPI (and other
  formats as well)

• Tools: some tools similar to swagger or http://editor.asyncapi.org/ should be
  quite easy to write

Stay tuned on : See https://lf-automotivelinux.atlassian.net/browse/SPEC-1903?page=com.atlassian.jira.plugin.system.issuetabpanels%3Aall-tabpanel for related JIRA entry. we'll update as soon as we have a proposal.