AGILE API specification documents

Welcome to the AGILE API specifications!

To read the API spec see this page

NOTE: This document is a work in progess that will be properly reviewed and finalized soon

In this repository we are going to define and version the internal API exposed by AGILE core modules via DBus IPC.

Contributing

Create an issue to suggest a modification or propose a change by creating a pull request.

Contributors shall follow those guidelines in order to get their contribution accepted.

##Specification

• The model should be a valid YAML document
• All method and property names are CamelCased, more precisely PascalCased
• All top level definitions may have a group text or text list to aggregate different object in categories. A tags list is used to aggregate different object on various topics.
• Methods must indicate a return type, with void if no return is expected and optionally a list of arguments
• Methods arguments must be a map with name as key and at least the type field specified as value
• Methods arguments and properties may have a default value to indicate a predefined value if non is specified.
• Asynchronous Methods must indicate a reference field indicating one or more Properties that receive updates from the call
• Properties referencing one object must have a reference field. If it is a list there will be a type Array with the reference field.
• Properties can indicate an access field as list of one of read, write, subscribe
• Optionally a description can be provided on methods, arguments and properties
• Optionally an example can be provided on methods, arguments and properties in a JSON like format, eg. example: { key1: value1, key2: value42 }
• Every object can expose an http field containing compliant Swagger 2.0 routes specifications

###Object description example

org.eclipse.agail.ObjectName:

  MethodName:
    description: <method description>
    arguments:
      arg1:
        description: <param description>
        type: <type>
    return: <return type>

  SimpleProperty:
    description: <method description>
    type: <type>
    access: [r, w, s]

  ReferenceProperties:
    description: <method description>
    reference: [org.eclipse.agail.AnotherObject]

Types:

@NOTE: Subtypes should be added accordingly and mapped to DBus supported types

• In case an Object or Array is specified a fields field should be added to describe the content.
• Use an * to indicate a complex variable (like Object and Array) has non specified return type, eg. Object*
• Enum should be defined in the same document of the object using it, eventually with an unique name inside the whole specs
• Enum should be defined as autonomous types with a field enum and a list of fields with keys
• void indicates a null value

Primitive types:

• Number: eg. 1, 5.9, -0.1
• String: eg. "Anything in double quotes :)"
• Boolean: eg. true or false

Structured types:

• Enum: a list of predefined keys

StatusType:
  type: Enum
  fields:
    - CONNECTED
    - DISCONNECTED

• Object: a group of structured informations

ObjName:
  type: Object
  fields:
    name: String
    id: Number
    address: String

• Array: an ordered list containing one or more types

ArrayField:
  type: Array
  fields:  String

Example definition

org.eclipse.agail.Device:
  Name:
    description: The device name
    type: String
   Status :
    description: Indicate the current device status
    type: StatusType
  Profile:
    description: Contains user provided information on device in order to handle at Protocol level the specific implementation
    type: Object*
  Protocol:
    description: Protocol instance
    reference: org.eclipse.agail.Protocol
  Read:
    args:
      sensorName: String
    return: Object

References

• API generation tool
• DBus API design
• JSON schema
• AGILE website
• Get in touch