Database API

Overview

The Mongodb interface API is implemented in flask and allows for restful access to the contained data. The system hosts itself at /pavement and allows for access through the general crud requests of POST, GET, DELETE, and PATCH.

Table of Contents

• Running the API
• Using the API
  • Creating
  • Retrieving Data
  • Updating Data
  • Deleting Data
  • Adding Images
• Troubleshooting
• Updates

Installation and Running

The API runs in a docker container which will install the necessary libraries and applications for you.

As such, the installation process is more straight forward than for many other systems

1. Download docker compose

   • Windows: https://docs.docker.com/docker-for-windows/install/
   • Mac : https://docs.docker.com/docker-for-mac/install/
   • Linux : https://docs.docker.com/install/linux/docker-ce/ubuntu/

2. a. Run the docker container (Assumed from linux)

   • sudo dockerd &
   • cd ~/Street-Watch/PavementApp
   • docker-compose up --build

3. b. Run the test docker container

   • sudo dockerd &
   • cd ~/Street-Watch/PavementApp
   • docker-compose -f ~/Street-Watch/PavementApp/docker-compose.yml -f ~/Street-Watch/PavementApp/docker-compose.test.yml up --build

4. b. Test the API

   • docker exec flask python -m unittest

After all the initialization is complete, the server will be available at localhost:4000/pavement.

Interface

The API allows for two main kinds of requests: batch, and individual.

Creating Data

For creation of data, both batch and individual requests are handled through the same interface. A POST request containing JSON can be send to /pavement. This will add the received data to the database.

An example of a well formed request would be POST /pavement JSON [{data:1},{data:2}]

and a response would be

{ "href": [ "/pavement/5cb0f1dd29ea30000166f824", "/pavement/5cb0f1dd29ea30000166f825", ], "id": [ "5cb0f1dd29ea30000166f824", "5cb0f1dd29ea30000166f825", ], "message": "Inserted 2 documents" } with a code of 201.

Retrieving Data

To batch search and display data in the database, you may send a GET request which can contain query parameters. If any results results are found, all results are returned as a response.

An example of a well formed request for batch retrieval would be GET /pavement JSON {data:1}

and a response would be

{results:[{_id:5cb0f1dd29ea30000166f824, data:1}, {_id:_id:5cb0f1dd29ea30000166f825, data:1}]} with a code of 200.

For individual retrieval of data, sending a GET request directly to a url will return the data with a matching object id.

An example of a well formed request for individual retrieval would be GET /pavement/5cb0f1dd29ea30000166f824

and a response would be

{result:{_id:5cb0f1dd29ea30000166f824, data:1}} with a code of 200.

Updating Data

Updating data can only be done through an individual PATCH request to a specific id. Similar to the creation requests, the JSON must contain query parameters. In this case: "$set". Additional information can be found on the MongoDB tutorial.

An example of a well formed request for updating data would be PATCH /pavement/5cb0f1dd29ea30000166f824 JSON {{"$set":{data:2}}

and a response would be (containing the object id of the edited data) {"id":"5cb0f1dd29ea30000166f824", "href":"/pavement/5cb0f1dd29ea30000166f824"}

Deleting Data

To batch delete data in the database, you may send a DELETE request which can contain query parameters. If any results results are found, all results are deleted, and a messsage is returned as a response.

An example of a well formed request for batch retrieval would be DELETE /pavement JSON {data:1}

and a response would be {message:"Deleted 2 result(s)} with a code of 200

For individual deletion of data, sending a DELETE request directly to a url will delete the data with a matching object id.

An example of a well formed request for individual retrieval would be DELETE /pavement/5cb0f1dd29ea30000166f824

and a response would be

{message:"Deleted _id: 5cb0f1dd29ea30000166f824"} with a code of 200.

Adding images

To add an image to an entry in the database, send a POST request to the object id of the entry you want to add the image to.

The file should be named "file" and the file will be added to the entry in the database and an href will be returned to the sender.

a response would be

{message:"Added image", href: "/pavement/images/5cb0f1dd29ea30000166f824.jpg"} with a code of 201.

More information can be seen on the API help page.

Troubleshooting

Cannot access localhost:4000

After building the container through the docker-compose up --build command, if no url is showing to access the Web API (ex: localhost:4000):

• If using the Docker Toolbox, open the Kinematic Docker API
• Find the Access URL on the righthand side (ex: 192.168.99.100:4000)
• Use the Acess URL within your browser to access the Web API

Updates