Writing Device APIs

The following subsections explain how to write and secure device APIs:

1. Create a JAXRS web application for APIs. 

   For more information, see the JAXRS implementation for APIs in Raspberry Pi.

2. Annotate the web app with the name and context, so that all the APIs of a device are grouped and can be identified instantly.
   Example: All the APIs will be grouped under raspberryPi

   @SwaggerDefinition(
           info = @Info(
                   version = "1.0.0",
                   title = "",
                   extensions = {
                           @Extension(properties = {
                                   @ExtensionProperty(name = "name", value = "raspberrypi"),
                                   @ExtensionProperty(name = "context", value = "/raspberrypi"),
                           })
                   }
           ),
           tags = {
                   @Tag(name = "raspberrypi", description = "")
           }

3. Annotate the APIs using the swagger annotations.  For more information on swagger annotations, see Annotations-1.5.X. 
   Example:

   @Path("device/{deviceId}/bulb")
   @POST
   @Scope(key = "device:raspberrypi:enroll", name = "", description = "")
   Response switchBulb(@PathParam("deviceId") String deviceId, @QueryParam("state") String state);

4. The resources used by external entities can be secured with WSO2 API Manager by including specific XML elements to the web.xml file of the web application that implements the APIs.

    Click here to view a configured web.XML file

   <?xml version="1.0" encoding="utf-8"?>
   <web-app version="2.5"
       xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
            metadata-complete="true">
       <display-name>RaspberryPi</display-name>
       <description>RaspberryPi</description>
       <servlet>
           <servlet-name>CXFServlet</servlet-name>
           <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
           <load-on-startup>1</load-on-startup>
       </servlet>
       <servlet-mapping>
           <servlet-name>CXFServlet</servlet-name>
           <url-pattern>/*</url-pattern>
       </servlet-mapping>
       <context-param>
           <param-name>isAdminService</param-name>
           <param-value>false</param-value>
       </context-param>
       <context-param>
           <param-name>doAuthentication</param-name>
           <param-value>true</param-value>
       </context-param>
       <context-param>
           <param-name>isSharedWithAllTenants</param-name>
           <param-value>true</param-value>
       </context-param>
       <context-param>
           <param-name>providerTenantDomain</param-name>
           <param-value>carbon.super</param-value>
       </context-param>
       <!--publish to apim-->
       <context-param>
           <param-name>managed-api-enabled</param-name>
           <param-value>true</param-value>
       </context-param>
       <context-param>
           <param-name>managed-api-owner</param-name>
           <param-value>admin</param-value>
       </context-param>
   </web-app>

    Click here for more information on the XML properties

   JAXRS web applications are used to create and configure APIs. By default, a web application has a web.xml file. WSO2 IoTS secures the APIs through web.xml by configuring it as shown below:

   XML Property	Description
   doAuthentication	APIs can be unauthenticated or authenticated where each API header will be validated to see if it meets the required conditions. If it's configured as true, the API is authenticated, and if it's configured as false, the API is unauthenticated.
   isSharedWithAllTenants	Optional. If this tag is included in the web.xml file and is configured as true, it indicates that the APIs are shared with all the tenants. If it's configured as false, it indicates that the APIs are restricted to the tenant that created them. If this tag is not present in the web.xml file, the default action would be to share the APIs with all the tenants.
   providerTenantDomain	Optional. Define the domain of the tenant. If this tag is not present in the web.xml file, carbon.super is taken as the default tenant domain.
   managed-api-enabled	WSO2 IoTS uses WSO2 API manager to secure APIs. The controller APIs are exposed to the public, whereas device management APIs are not exposed to the public as they are used to communicate internally. The API Manager has a gateway to handle the calls made to an API, and each time a specific API is called a token is generated. The following values can be assigned to the XML property managed-api-enabled: true - The APIs in the respective JAXRS web application are secured via the API Manager. There will be a token issued to secure the API each time the API is called via the API Manager gateway. If managed-api-enabled is true, the APIs in the web application are identified as controller APIs in the context of WSO2 IoTS. false -  The APIs in the respective JAXRS web application is not secured via the API Manager. If managed-api-enabled is false, the APIs in the web application are identified as device manager APIs in the context of WSO2 IoTS. For example of setting managed-api-enabled to false: <context-param> <param-name>managed-api-enabled</param-name> <param-value>false</param-value> </context-param>
   managed-api-owner	The owner of the APIs. By default the value defined is admin. In the context of multi-tenancy, you need to define the owner of the managed APIs, as WSO2 IoTS will then be supporting different tenants. Example: <context-param> <param-name>managed-api-owner</param-name> <param-value>admin</param-value> </context-param>
   isAdminService	Define if the APIs need or need not be exposed as admin services.