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.
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. Atags
list is used to aggregate different object on various topics. - Methods must indicate a
return
type, withvoid
if no return is expected and optionally a list ofarguments
- Methods
arguments
must be a map with name as key and at least thetype
field specified as value - Methods
arguments
andproperties
may have adefault
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 typeArray
with thereference
field. - Properties can indicate an
access
field as list of one ofr
ead,w
rite,s
ubscribe - 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 compliantSwagger 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]
@NOTE: Subtypes should be added accordingly and mapped to DBus supported types
- In case an
Object
orArray
is specified afields
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 offields
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
orfalse
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
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