Skip to content

RESTful API

Jump to bottom
Ki-Joune Li edited this page Jul 31, 2018 · 37 revisions

Introduction

User can use InFactory regardless of the development environment via RESTful API of InFactory. RESTful API is based on CRUD function on IndoorGML complex features. Users can create IndoorGML by writing their own indoor space information according to the predefined JSON(Javascript Object Notation) based form.

JSON format

All IndoorGML complex features can be represented by this JSON format. The details are described at JSON-format

How to use

First of all, the users need to implement their own client program which sends HTTP requests to the server. If there is no client program, it is recommended to use InSomnia, which is a debugging tool for RESTful API by by communicating HTTP request to the server program.

Insomnia

Quick Start

Terms

  • POST: Request to create a new entity including a document and the features in IndoorGML
  • GET: Retrieve information from InFactory server.
  • PUT: Request to update the existing entity. InFactory supports fully-patched Update.
  • DELETE: Request to remove a resource; however, the resource does not have to be removed immediately.

1. How to run InFactory server

After installing Infactory as explained in Readme, you have to make InFactory server ready to receive the HTTP requests from your client.

$ mvn clean install
$ mvn jetty:run "-Djetty.port=9797"

2. Creating an IndoorGML Document

You can create an IndoorGML document by sending a set of HTTP requests to the InFactory server. The creation procedure is in general composed of the following steps;

  • Step 1: Creating IndoorGML document (POST request)
  • Step 2: Creating IndoorGML Features (POST request)
  • Step 3: Downloading IndoorGML document (GET request) Each step of the procedure is explained below.

3. POST

First of all, you have to give the name of IndoorGML document as a URL, for example, http://localhost:9797/documents/doc1. Although the users of InFactory do not need to care the sequence of feature creations and the IndoorGML class hierarchy, the key features shown in figure 1 should not be missing anyway.

IndoorFeatures
              |-> PrimalSpaceFeatures
                                    |-> CellSpace
                                    |-> CellSpaceBoundary
              |-> MultiLayeredGraph -> SpaceLayers -> SpaceLayer
                                                                |-> Nodes -> State
                                                                |-> Edges -> Transition

Figure 1. Basic IndoorGML Hierarchical Structure

When the user sends GET request to the InFactory server, it generates the IndoorGML document by arranging the hierarchical structure of the document.

Example code with Javascript
var req = new XMLHttpRequest();
req.open('POST', 'http://localhost:9797/documents/:id');
req.setRequestHeader('Content-type', 'application/json');
req.send(JSON.stringify({
  docId: "doc1"
}));

req.onreadystatechange = function (e) {
  if (req.readyState === XMLHttpRequest.DONE) {
    if(req.status === 201) {
      console.log(req.responseText);
    } else {
      console.log("Error!");
    }
  }
};
2.1. Create Document

First of all, It is needed to create a document

URL

/documents/:id

  • parameter : id=[alphanumeric id which starts as a alphabet]
Example of the url
$ POST http://localhost:9797/documents/doc1
Body
  • Content-Type : "application/json"
  • Accept : "application/json"
{
    "id":"doc1"
}
Response
  • Status : 201 created / 404 NOT FOUND
  • Content-Type : None
2.2. Create Indoorfeatures

Next, the Indoorfeatures feature can be created by sending the below request to the server.

InFactory support unordered creation of the feature in IndoorGML.

URL

/documents/:docId/indoorfeatures/:id

  • parameter : docId | id =[alphanumeric id which starts as a alphabet]
Example of the url
$ POST http://localhost:9797/documents/doc1/indoorfeatures/if1
Body
  • Content-Type : "application/json"
  • Accept : "application/json"
{
    "docId":"doc1", //the id of the document which this elements are contained.
    "id":"lf1" //the id of the feature.
}
Response
  • Status : 201 created / 404 NOT FOUND
  • Content-Type : None
2.3. Create PrimalSpaceFeatures
URL

/documents/:docId/primalspacefeatures/:id

  • parameter : docId | id =[alphanumeric id which starts as a alphabet]
Example of the url
$ POST http://localhost:9797/documents/doc1primalspacefeatures/pf1
Body
  • Content-Type : "application/json"
  • Accept : "application/json"
{
    "docId":"doc1",
    "parentId":"lf1",
    "id":"psf1"
}
Response
  • Status : 201 created / 404 NOT FOUND
  • Content-Type : None
2.4. Create CellSpace
URL

/documents/:docId/cellspace/:id

  • parameter : docId | id =[alphanumeric id which starts as a alphabet]
Example of the URL
$ POST http://localhost:9797/documents/doc1/cellspace/c1
Body
  • Content-Type : "application/json"
  • Accept : "application/json"
{
    "docId":"doc1",
    "parentId":"psf1",
    "id":"c1",
    "geometry": {
        "type" : "Solid",
        "coordinates" : "SOLID (( ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 0 1 0, 0 1 1, 0 0 1, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), ((1 1 1, 1 0 1, 0 0 1, 0 1 1, 1 1 1)), ((1 1 1, 1 0 1, 1 0 0, 1 1 0, 1 1 1)), ((1 1 1, 1 1 0, 0 1 0, 0 1 1, 1 1 1)) ))",
        "properties" : {
            "id" : "c1g",
            "type" : "wkt"
        }
    }
}
Response
  • Status : 201 created / 404 NOT FOUND
  • Content-Type : None

3. GET

Example code of Javascript
var req = new XMLHttpRequest();
req.open('GET', 'http://localhost:9797/documents/doc1/cellspace/c1');
req.send();

req.onreadystatechange = function (e) {
  if (req.readyState === XMLHttpRequest.DONE) {
    if(req.status === 302) {
      console.log(req.responseText);
    } else {
      console.log("Error!");
    }
  }
};
3.1. GET documents

The request is sent as the below.

URL

/documents/:docId

  • parameter : docId =[alphanumeric id which starts as a alphabet]
Example of the url
$ GET http://localhost:9797/documents/doc1/
Body
  • Content-Type : None
  • Accept : None
Response
  • Status : 302 FOUND / 404 NOT FOUND
  • Content-Type : "application/xml"
<IndoorFeatures
    xmlns:gml="http://www.opengis.net/gml/3.2"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns="http://www.opengis.net/indoorgml/1.0/core"
    xmlns:navi="http://www.opengis.net/indoorgml/1.0/navigation"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" gml:id="lf1" xsi:schemaLocation="http://www.opengis.net/indoorgml/1.0/core http://schemas.opengis.net/indoorgml/1.0/indoorgmlcore.xsd http://www.opengis.net/indoorgml/1.0/navigation http://schemas.opengis.net/indoorgml/1.0/indoorgmlnavi.xsd">
    <gml:boundedBy xsi:nil="true"/>
    <primalSpaceFeatures>
        <PrimalSpaceFeatures gml:id="psf1">
            <gml:boundedBy xsi:nil="true"/>
            <cellSpaceMember>
                <CellSpace gml:id="c1">
                    <gml:boundedBy xsi:nil="true"/>
                    <cellSpaceGeometry>
                        <Geometry3D>
                            <gml:Solid gml:id="c1g">
                                <gml:exterior>
                                    <gml:Shell>
                                        <gml:surfaceMember>
                                            <gml:Polygon>
                                                <gml:exterior>
                                                    <gml:LinearRing>
                                                        <gml:pos srsDimension="3">0.0 0.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 1.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 1.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 0.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 0.0 0.0</gml:pos>
                                                    </gml:LinearRing>
                                                </gml:exterior>
                                            </gml:Polygon>
                                        </gml:surfaceMember>
                                        <gml:surfaceMember>
                                            <gml:Polygon>
                                                <gml:exterior>
                                                    <gml:LinearRing>
                                                        <gml:pos srsDimension="3">0.0 0.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 1.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 1.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 0.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 0.0 0.0</gml:pos>
                                                    </gml:LinearRing>
                                                </gml:exterior>
                                            </gml:Polygon>
                                        </gml:surfaceMember>
                                        <gml:surfaceMember>
                                            <gml:Polygon>
                                                <gml:exterior>
                                                    <gml:LinearRing>
                                                        <gml:pos srsDimension="3">0.0 0.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 0.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 0.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 0.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 0.0 0.0</gml:pos>
                                                    </gml:LinearRing>
                                                </gml:exterior>
                                            </gml:Polygon>
                                        </gml:surfaceMember>
                                        <gml:surfaceMember>
                                            <gml:Polygon>
                                                <gml:exterior>
                                                    <gml:LinearRing>
                                                        <gml:pos srsDimension="3">1.0 1.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 0.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 0.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 1.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 1.0 1.0</gml:pos>
                                                    </gml:LinearRing>
                                                </gml:exterior>
                                            </gml:Polygon>
                                        </gml:surfaceMember>
                                        <gml:surfaceMember>
                                            <gml:Polygon>
                                                <gml:exterior>
                                                    <gml:LinearRing>
                                                        <gml:pos srsDimension="3">1.0 1.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 0.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 0.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 1.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 1.0 1.0</gml:pos>
                                                    </gml:LinearRing>
                                                </gml:exterior>
                                            </gml:Polygon>
                                        </gml:surfaceMember>
                                        <gml:surfaceMember>
                                            <gml:Polygon>
                                                <gml:exterior>
                                                    <gml:LinearRing>
                                                        <gml:pos srsDimension="3">1.0 1.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 1.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 1.0 0.0</gml:pos>
                                                        <gml:pos srsDimension="3">0.0 1.0 1.0</gml:pos>
                                                        <gml:pos srsDimension="3">1.0 1.0 1.0</gml:pos>
                                                    </gml:LinearRing>
                                                </gml:exterior>
                                            </gml:Polygon>
                                        </gml:surfaceMember>
                                    </gml:Shell>
                                </gml:exterior>
                            </gml:Solid>
                        </Geometry3D>
                    </cellSpaceGeometry>
                </CellSpace>
            </cellSpaceMember>
        </PrimalSpaceFeatures>
    </primalSpaceFeatures>
</IndoorFeatures>
3.2. GET CellSpace
URL

/documents/:docId/cellspace/:id

  • parameter : docId | id =[alphanumeric id which starts as a alphabet]
Example of the url
$ GET http://localhost:9797/documents/doc1/cellspace/c1
Body
  • Content-Type : None
  • Accept : None
Response
  • Status : 302 FOUND / 404 NOT FOUND
  • Content-Type : "application/json"
{
    "docId":"doc1",
    "parentId":"psf1",
    "id":"c1",
    "geometry": {
        "type" : "Solid",
        "coordinates" : "SOLID (( ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 0 1 0, 0 1 1, 0 0 1, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), ((1 1 1, 1 0 1, 0 0 1, 0 1 1, 1 1 1)), ((1 1 1, 1 0 1, 1 0 0, 1 1 0, 1 1 1)), ((1 1 1, 1 1 0, 0 1 0, 0 1 1, 1 1 1)) ))",
        "properties" : {
            "id" : "c1g",
            "type" : "wkt"
        }
    }
}

4. PUT

InFactory changes the contents of the existing features fully when Infactory receives "PUT" request.

Example code of Javascript
var req = new XMLHttpRequest();
req.open('PUT', 'http://localhost:9797/documents/doc1/cellspace/c1');
req.setRequestHeader('Content-type', 'application/json');
req.send(JSON.stringify({
  type : "CellSpace",
  docId : "doc1" ,
  parentId : "psf1",
  id : "c1",
  geometry : {
    "type" : "Solid",
       coordinates : "SOLID (( ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 0 1 0, 0 1 1, 0 0 1, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), ((1 1 1, 1 0 1, 0 0 1, 0 1 1, 1 1 1)), ((1 1 1, 1 0 1, 1 0 0, 1 1 0, 1 1 1)), ((1 1 1, 1 1 0, 0 1 0, 0 1 1, 1 1 1)) ))",
       properties : {
           id : "c1g",
           type : "wkt"
  }

}));

req.onreadystatechange = function (e) {
  if (req.readyState === XMLHttpRequest.DONE) {
    if(req.status === 200) {
      console.log(req.responseText);
    } else {
      console.log("Error!");
    }
  }
};
URL

/documents/:docId/cellspace/:id

  • parameter : docId | id =[alphanumeric id which starts as a alphabet]
Example of the url
$ PUT http://localhost:9797/documents/doc1/cellspace/c1
Body
  • Content-Type : "application/json"
  • Accept : "application/json"
{
    "docId":"doc1",
    "parentId":"psf1",
    "id":"c1",
    "geometry": {
        "type" : "Solid",
        "coordinates" : "SOLID (( ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 0 1 0, 0 1 1, 0 0 1, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), ((1 1 1, 1 0 1, 0 0 1, 0 1 1, 1 1 1)), ((1 1 1, 1 0 1, 1 0 0, 1 1 0, 1 1 1)), ((1 1 1, 1 1 0, 0 1 0, 0 1 1, 1 1 1)) ))",
        "properties" : {
            "id" : "c1g",
            "type" : "wkt"
        }
    }
}
Response
  • Status : 201 CREATED / 404 NOT FOUND
  • Content-Type : None

5. DELET

This request removes CellSpace "c1" at the server.

Example code with Javascript
var req = new XMLHttpRequest();
req.open('DELETE', 'http://localhost:9797/documents/doc1/cellspace/c1');
req.send();

req.onreadystatechange = function (e) {
  if (req.readyState === XMLHttpRequest.DONE) {
    if(req.status === 204) {
      console.log(req.responseText);
    } else {
      console.log("Error!");
    }
  }
};
URL

/documents/:docId/cellspace/:id

  • parameter : docId | id =[alphanumeric id which starts as a alphabet]
Example of the url
$ DELETE http://localhost:9797/documents/doc1/cellspace/c1
Body
  • Content-Type : None
  • Accept : None
Response
  • Status : 204 NO CONTENT / 404 NOT FOUND
  • Content-Type : None

Quick Start

Advanced

Clone this wiki locally