This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Page Comparison - Writing Device APIs (v.1 vs v.2) - IoT Server 3.1.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Create a JAXRS web application for APIs. 

    Info

    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

    Code Block
    @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:

    Code Block
    @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.

    Info
    Expand
    titleClick here to view a configured web.XML file
    Code Block
    <?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>doAuthentication</param-name>
            <param-value>true</param-value>
        </context-param>
        <context-param>
            <param-name>isSharedWithAllTenants</param-name>
            <param-value>true</param-value>
        </context-param>
        <!--publish to apim-->
        <context-param>
            <param-name>managed-api-enabled</param-name>
            <param-value>true</param-value>
        </context-param>
    </web-app>
    Expand
    titleClick here for more information on the XML properties
    Excerpt
    Panel
    bgColor#ffffff

    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 PropertyDescription
    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.

    Info

    If this tag is not present in the web.xml file, the default action would be to share the APIs with all the tenants.

    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.

      Info

      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.

      Info

      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:

    Code Block
    <context-param>
       <param-name>managed-api-enabled</param-name>
       <param-value>false</param-value>
    </context-param>