@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api AWS IoT 1-Click Devices Service
@version 2018-05-14
@auth AWS SigV4
@endpoints 13
@toc claims(1), devices(9), tags(3)

@group claims
@endpoint PUT /claims/{claimCode}
@desc Adds device(s) to your account (i.e., claim one or more devices) if and only if you
 received a claim code with the device(s).
@required {ClaimCode: str}
@returns(200) {ClaimCode: str?, Total: int?}

@endgroup

@group devices
@endpoint GET /devices/{deviceId}
@desc Given a device ID, returns a DescribeDeviceResponse object describing the
 details of the device.
@required {DeviceId: str}
@returns(200) {DeviceDescription: DeviceDescription?{Arn: str?, Attributes: map<str,str>?, DeviceId: str?, Enabled: bool?, RemainingLife: num(f64)?, Type: str?, Tags: map<str,str>?}}

@endpoint PUT /devices/{deviceId}/finalize-claim
@desc Given a device ID, finalizes the claim request for the associated device.
 Claiming a device consists of initiating a claim, then publishing a device event,
 and finalizing the claim. For a device of type button, a device event can
 be published by simply clicking the device.
@required {DeviceId: str}
@optional {Tags: map<str,str>}
@returns(200) {State: str?}

@endpoint GET /devices/{deviceId}/methods
@desc Given a device ID, returns the invokable methods associated with the device.
@required {DeviceId: str}
@returns(200) {DeviceMethods: [DeviceMethod]?}

@endpoint PUT /devices/{deviceId}/initiate-claim
@desc Given a device ID, initiates a claim request for the associated device.
 Claiming a device consists of initiating a claim, then publishing a device event,
 and finalizing the claim. For a device of type button, a device event can
 be published by simply clicking the device.
@required {DeviceId: str}
@returns(200) {State: str?}

@endpoint POST /devices/{deviceId}/methods
@desc Given a device ID, issues a request to invoke a named device method (with possible
 parameters). See the "Example POST" code snippet below.
@required {DeviceId: str}
@optional {DeviceMethod: DeviceMethod, DeviceMethodParameters: str}
@returns(200) {DeviceMethodResponse: str?}

@endpoint GET /devices/{deviceId}/events
@desc Using a device ID, returns a DeviceEventsResponse object containing an
 array of events for the device.
@required {DeviceId: str, fromTimeStamp: str(timestamp), toTimeStamp: str(timestamp)}
@optional {maxResults: int, nextToken: str}
@returns(200) {Events: [DeviceEvent]?, NextToken: str?}

@endpoint GET /devices
@desc Lists the 1-Click compatible devices associated with your AWS account.
@optional {deviceType: str, maxResults: int, nextToken: str}
@returns(200) {Devices: [DeviceDescription]?, NextToken: str?}

@endgroup

@group tags
@endpoint GET /tags/{resource-arn}
@desc Lists the tags associated with the specified resource ARN.
@required {ResourceArn: str}
@returns(200) {Tags: map<str,str>?}

@endpoint POST /tags/{resource-arn}
@desc Adds or updates the tags associated with the resource ARN. See AWS IoT 1-Click Service Limits for the maximum number of tags allowed per
 resource.
@required {ResourceArn: str, Tags: map<str,str>}

@endgroup

@group devices
@endpoint PUT /devices/{deviceId}/unclaim
@desc Disassociates a device from your AWS account using its device ID.
@required {DeviceId: str}
@returns(200) {State: str?}

@endgroup

@group tags
@endpoint DELETE /tags/{resource-arn}
@desc Using tag keys, deletes the tags (key/value pairs) associated with the specified
 resource ARN.
@required {ResourceArn: str, tagKeys: [str]}

@endgroup

@group devices
@endpoint PUT /devices/{deviceId}/state
@desc Using a Boolean value (true or false), this operation
 enables or disables the device given a device ID.
@required {DeviceId: str}
@optional {Enabled: bool}

@endgroup

@end