io.relayr.java.api.DeviceApi Maven / Gradle / Ivy

Go to download
package io.relayr.java.api;

import java.util.List;

import io.relayr.java.model.CreateDevice;
import io.relayr.java.model.Device;
import io.relayr.java.model.action.Command;
import io.relayr.java.model.action.Configuration;
import io.relayr.java.model.models.schema.ValueSchema;
import io.relayr.java.model.models.transport.DeviceCommand;
import io.relayr.java.model.models.transport.DeviceConfiguration;
import io.relayr.java.model.models.transport.DeviceReading;
import io.relayr.java.model.state.State;
import io.relayr.java.model.state.StateCommands;
import io.relayr.java.model.state.StateConfigurations;
import io.relayr.java.model.state.StateMetadata;
import io.relayr.java.model.state.StateReadings;
import retrofit.http.Body;
import retrofit.http.DELETE;
import retrofit.http.GET;
import retrofit.http.PATCH;
import retrofit.http.POST;
import retrofit.http.Path;
import retrofit.http.Query;
import rx.Observable;

/** This class incorporates a wrapped version of the relayr device API calls. */
public interface DeviceApi {

    /**
     * Creates device on the platform.
     * @param device to create
     * @return created device
     */
    @POST("/devices") Observable createDevice(@Body CreateDevice device);

    /**
     * Updates a device.
     * @param deviceId id of the device to update
     * @param device   updated device with the new details
     * @return an {@link Observable} to the updated Device
     */
    @PATCH("/devices/{id}")
    Observable updateDevice(@Path("id") String deviceId, @Body Device device);

    /**
     * Deletes a device from platform.
     * @param deviceId id of device to delete
     * @return 200 OK if successful
     */
    @DELETE("/devices/{id}") Observable deleteDevice(@Path("id") String deviceId);

    /**
     * A public device is a device which public attribute has been set to 'true' therefore
     * no authorization is required.
     * @param meaning When a meaning is specified, the request returns only
     *                the devices which readings match the meaning.
     * @return an {@link Observable} with a list of all public devices.
     */
    @GET("/devices/public")
    Observable> getPublicDevices(@Query("meaning") String meaning);

    /**
     * Send command defined by device models {@link DeviceCommand}
     * Before sending a command make sure to validate it by calling {@link Command#validate(ValueSchema)}
     */
    @POST("/devices/{id}/commands")
    Observable sendCommand(@Path("id") String deviceId, @Body Command command);

    /**
     * Sets device configuration defined by device models {@link DeviceConfiguration}
     * Before sending a command make sure to validate it by calling {@link Configuration#validate(ValueSchema)}
     */
    @POST("/devices/{id}/configurations")
    Observable sendConfiguration(@Path("id") String deviceId,
                                       @Body Configuration configuration);

    /**
     * Persists user defined object in device state {@link State} metadata
     * @param deviceId unique device identifier
     * @param key      unique key in metadata dictionary
     * @param metadata user defined object
     */
    @POST("/devices/{id}/metadata") Observable setMetadata(@Path("id") String deviceId,
                                                                 @Query("key") String key,
                                                                 @Body Object metadata);

    /**
     * Returns device's {@link State}.
     * Device state shows latest state of devices' readings, configuration, commands and metadata.
     * @param deviceId unique device identifier
     */
    @GET("/devices/{id}/state") Observable getState(@Path("id") String deviceId);

    /**
     * Returns device's {@link StateMetadata}
     * @param deviceId unique device identifier
     * @param key      key to filter metadata dictionary
     */
    @GET("/devices/{id}/metadata")
    Observable getMetadata(@Path("id") String deviceId,
                                          @Query("key") String key);

    /**
     * Returns device's {@link StateReadings}
     * Path and meaning parameters are optional. If provided used as regular filter fields.
     * @param deviceId unique device identifier
     * @param path     defined by {@link DeviceReading#getPath()} in {@link io.relayr.java.model.models.DeviceModel}
     * @param meaning  defined by {@link DeviceReading#getMeaning()} in {@link io.relayr.java.model.models.DeviceModel}
     */
    @GET("/devices/{id}/readings")
    Observable getReadings(@Path("id") String deviceId,
                                          @Query("path") String path,
                                          @Query("meaning") String meaning);

    /**
     * Returns device's {@link StateCommands}
     * Path and name parameters are optional. If provided used as regular filter fields.
     * @param deviceId unique device identifier
     * @param path     defined by {@link DeviceCommand#getPath()} in {@link io.relayr.java.model.models.DeviceModel}
     * @param name     defined by {@link DeviceCommand#getName()} in {@link io.relayr.java.model.models.DeviceModel}
     */
    @GET("/devices/{id}/commands")
    Observable getCommands(@Path("id") String deviceId,
                                          @Query("path") String path,
                                          @Query("name") String name);

    /**
     * Returns device's {@link StateConfigurations}
     * Path and name parameters are optional. If provided used as regular filter fields.
     * @param deviceId unique device identifier
     * @param path     defined by {@link DeviceConfiguration#getPath()} in {@link io.relayr.java.model.models.DeviceModel}
     * @param name     defined by {@link DeviceConfiguration#getName()} in {@link io.relayr.java.model.models.DeviceModel}
     */
    @GET("/devices/{id}/configurations")
    Observable getConfigurations(@Path("id") String deviceId,
                                                      @Query("path") String path,
                                                      @Query("name") String name);
}