apiary.apib

FORMAT: 1A
HOST: https://dronedevmeetup.docs.apiary.io/

# Drone
Defines a set of APIs that can be used to command a Drone. Whilst not bound specifically to the Parrot Drone SDK
its use is initially targeted to support the Parrot Drone SDK and Bebop II specifically.
The SDK URL is http://developer.parrot.com/docs/reference/bebop_2/index.html#scan-wifi-network97.

All the APIs will use an API-Key to secure the interaction. Each drone will have an identifier passed as a header.
That will enable the API implementation to be used for managing multiple drones.

As it is possible for an API call to be received whilst handling an existing API call qwhen a conflict has occured HTTP response code of 409 will be provided.

The APIs will be implemented progressively - for APIs not yet implemented an HTTP response of 501 will be returned 

## Register Drone [/drone/register]
Tell the microservices about the drone, so we can correlate Id to the correct drone

### Register [GET]
Triggers the process of locating drones. This then returns the drones and their identifiers
http://developer.parrot.com/docs/SDK3/#discover-the-drones

+ Request (application/json)

    + Headers

            api-key: YTkxZTRhNzAtODdlNy00ZjMzLTg0MWItOTc0NmZmNjU4Yzk4
        
            
+ Response 200 (application/json)
        
    + Attributes    
            + drones (array)
                + droneId: "1" (string)  - Drone Id to be used in all the subsequent API calls
                + droneDescription: droneInfo (string) - details of the drone located
                
+ Response 500
                
## Simple Yaw Movement [/drone/{droneId}/simplenav/rotation/{rotationValue}]
Movement provided by the URI as a simple operation one one axis can be controlled rotation.

### Change Yaw [PUT]
will make the drone change its rotation value in the range of -100 to 100

+ Request (application/json)

    + Headers

            api-key: YTkxZTRhNzAtODdlNy00ZjMzLTg0MWItOTc0NmZmNjU4Yzk4
            
+ Parameters

    + droneId (string, required)

        + Sample: 1
        
    + rotationValue (number, required)
    
        + Sample: 10

+ Response 200 (application/json)

+ Response 409 (text/plain)


## Simple Roll Movement [/drone/{droneId}/simplenav/roll/{rollValue}]
Movement provided by the URI as a simple operation one one axis can be controlled roll (left to right)  in the range of -100 to 100

### Change Roll [PUT]
will make the drone change its roll value  in the range of -100 to 100

+ Request (application/json)

    + Headers

            api-key: YTkxZTRhNzAtODdlNy00ZjMzLTg0MWItOTc0NmZmNjU4Yzk4
+ Parameters

    + droneId (string, required)

        + Sample: 1
        
    + rollValue (number, required)
    
        + Sample: 10

+ Response 200 (application/json)

+ Response 409 (text/plain)


## Simple Pitch Movement [/drone/{droneId}/simplenav/pitch/{pitchValue}]
Movement provided by the URI as a simple operation to control pitch (forward and backward)

### Change Pitch [PUT]
will make the drone change its pitch value. Legal values range from -100 to 100

+ Request (application/json)

    + Headers

            api-key: YTkxZTRhNzAtODdlNy00ZjMzLTg0MWItOTc0NmZmNjU4Yzk4
+ Parameters

    + droneId (string, required)

        + Sample: 1
        
    + pitchValue (number, required)
    
        + Sample: 10

+ Response 200 (application/json)

+ Response 409 (text/plain)

## Simple Altitude Movement [/drone/{droneId}/simplenav/altitude/{altitudeValue}]
Movement provided by the URI as a simple operation one one axis can be controlled altitude. Altitutde is technically identified as gaz

### Change Altitude [PUT]
will make the drone change its yaw value

+ Request (application/json)

    + Headers

            api-key: YTkxZTRhNzAtODdlNy00ZjMzLTg0MWItOTc0NmZmNjU4Yzk4
+ Parameters

    + droneId (string, required)

        + Sample: 1
        
    + altitudeValue (number, required)
    
        + Sample: 10

+ Response 200 (application/json)

+ Response 409 (text/plain)


## Combined Movement [/drone/{droneId}/move]

### Move Drone [PUT]
Returns all MRA Artists that match the specified criteria.

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b (String)
            droneId: 1234

    + Attributes
        
        + movement (Move)

+ Response 200 (text/plain)                

+ Response 409 (text/plain)


## Flight Movement [/drone/{droneId}/nav/move]
Movement commands based telling the drone what angles of yaw, role and rotation etc to use.

+ Parameters

    + droneId (string, required)

        + Sample: 1
    
### Move Drone [PUT]
Returns all MRA Artists that match the specified criteria.

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b (String)
            droneId: 1234

    + Attributes
        
        + movement (Move)

+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain) 


## Flight Movement by Location [/drone/{droneId}/nav/move-to]
Controlling drones can also be achieved by telling a drone a location to fly to rather than instructions relating to yaw, role etc

+ Parameters

    + droneId (string, required)

        + Sample: 1

### Move Drone To [PUT]
Returns all MRA Artists that match the specified criteria.

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b (String)
            
    + Attributes

        + goTo (Location)

+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain)

## Flight Commands [/drone/{droneId}/nav/action/{action}]
Provides the means to issue simple commands such as takeoff or land etc If the command is accepted then a 200 response is provided. 
If the request was understood, but could not be actioned because the drone was in the wrong state e.g. Land when the drone is Inactive or already Landed then 403 is provided
If the request hasnt been implemented yet then 501 is returned. For requests that arent understood 400 is returned

+ Parameters

    + droneId (string, required)

        + Sample: 1
        
    + action (enum, required)
    
        + Sample: takeoff, land, hover, cutpower, return, startFollowing, stopFollowing

### Command Drone [PUT]
Perform a specific action

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b (String)

+ Response 200 (text/plain)

+ Response 400 (text/plain)

+ Response 403 (text/plain)

+ Response 501 (text/plain)

## Flight Tricks [/drone/{droneId}/nav/tricks]

+ Parameters

    + droneId (string, required)

        + Sample: 1

### Command Drone [PUT]
Some drones are capable of performing predefined tricks. This API allows us to perform those tricks

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b (String)
        
    + Attributes
        
        + execute (Trick)
            
+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain)

## Camera Commands [/drone/{droneId}/camera/action?{cmd}]

+ Parameters

    + droneId (string, required)

        + Sample: 1
        
    + cmd: cmd1, cmd2 (enum, optional)
    
        + Sample: cmd1

### Command Camera [PUT]
Perform a specific action

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b

+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain)

## Manage The Connection Of The Drone [/drone/{droneId}/manage/connection]
Operations to manage the Drone network connectivity

+ Parameters

    + droneId (string, required)

        + Sample: 1
        

### Control Network For Drone [POST]
Controls the network settings for the drone.

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b

+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain)

## Manage Nav Limits [/drone/{droneId}/manage/nav]
Operations related to managing a drone flight such as setting limits on the flight details


+ Parameters

    + droneId (string, required)

        + Sample: 1
        
### Set Navigation Limits [PUT]
Identify a drone to the API implementation so the Id can be used to reference the specific drone to command

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b
    
    + Attributes
    
        + limits (MoveLimits)

+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain)

## Define Location [/drone/{droneId}/manage/nav/location]
Defines different types of location

+ Parameters

    + droneId (string, required)

        + Sample: 1

### Define Location [PUT]
Identify a drone to the API implementation so the Id can be used to reference the specific drone to command

+ Request (application/json)

    + Headers

            api-key: ac108161-d3a5-427d-b814-ff977728395b

    
    + Attributes
    
        + location (Location, required)
        
        + locationType: home, pilot (enum, required)

+ Response 200 (text/plain)

+ Response 409 (text/plain)

+ Response 501 (text/plain)

# Data Structures

## Move (object)
- yaw: 0.0 (number, required)

    Ranges from -100 to +100 and controls the drone rotation on its central axis. Negative values cause rotation anti clockwise and 
    positive causes rotation in clockwise manner

- roll: 0.0 (number, required) 

    ranges from -100 to +100 with negative values representing movement to the left and positive for movement to the right
    
- pitch: 0.0 (number, required)

    ranges from -100 to +100 with a negative value causing the drone front to rise skyward cause the drone to move backwards
    and the positive range making the front move downward to the ground and drone will move forwards
    
- gaz: 0.0 (number, required)

    ranges from -100 to + 100 and defines the rate of vertical movement. with a positive figure causing an increase in 
    height and negative value causing decent

## MoveLimits (object)
- maxYaw: 50 (number, optional) - maximum rate of yaw, rotation about drone centre
- maxRoll: 50 (number, optional) - maximum rate of roll, left to right
- maxPitch: 50 (number, optional) - maximum level of pitch, front to back
- maxAltitude: 5 (number, optional) - maximum height allowed
- maxDistance: 5 (number, optional) - maximum distance can be set from initial location
- maxGaz: 2 (number, optional) - maximum verticial acceleration

##EnvironmentSettings (object)
- environment: indoors (enum, required)

## HomeLocation (object)
- lat: 1.1234 (number, required)
- long: 1.234 (number, required)
- altitude: 0.5 (number, optional) alteritude in metres

## Location (object)
- lat: 1.1234 (number, required)
- long: 1.234 (number, required)
- altitude: 1.234 (number, required)
- heading: 1.2345 (number, optional)
- orientation: none, location, previous, during (enum, optional)

## LocationOffset (object)
- distance: 1.0 (number, required) - The distance leader-follower in meters
- elevation: 0.5 (number, required) - The elevation leader-follower in meters 
- azimuth: 0.0 (number, required) - The azimuth north-leader-follower in rad (not used when arg start is at 0)

## Action (object)
- action: takeoff,land, hover, cutpower, return, startFollowing, stopFollowing (enum, required)

## Trick (object)
- manuever: flip, horizontalReveal, verticalReveal, spiral, parabole, candle, dolly, (enum, required)