You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Blaine Motsinger 5780ef4f27 added /map[s] route to the README 1 year ago
app switching to Starman for the proxy server 1 year ago
db add support for map links between points 1 year ago
lib/Rend/Map slight formatting change to the pod 1 year ago
public_html added back htaccess 1 year ago
scripts added script to generate and compare passphrases 1 year ago
t fixed tests 1 year ago
.gitignore added scratch txt to gitignore 1 year ago
.travis.yml added missing dep to install 1 year ago
LICENSE added MIT license 1 year ago
README.md added /map[s] route to the README 1 year ago

README.md

Build Status Coverage Status

rendmap

map point API in Perl

DESCRIPTION

This project provides an API, written in Perl, which serves and stores GPS coordinates.

DEPENDENCIES

strictures
File::HomeDir
DBI
DBD::mysql
Moo
Dancer2 (lots of dependencies)
Dancer2::Plugin::Passphrase

SETUP

CONFIGURATION

.maprc

The database connection details are read from the .maprc file, located in the user’s homedir.

~ $ cat .maprc
# rendmap rc
host:localhost
database:database_name
username:database_user
password:password_goes_here

The .maprc file is read when the database handle is created and will die if the file doesn’t exist. The file is not checked into the project and will need to be manually created.

ENVIRONMENT SPECIFIC CONFIGURATION

There are 3 files within the app directory which define environment specific settings.

config.yml

This file defines Dancer2 directives which apply to both the development and production environments.

~/app (master) $ cat config.yml                      
appname: 'rendmap'
startup_info: 1
serializer: 'JSON'
development.yml

This file defines Dancer2 directives which apply to the development environment.

~/app/environments (master) $ cat development.yml                      
logger: 'Console'
log_level: 'core'
show_errors: 1
warnings: 1
traces: 1
engines:
    serializer:
        JSON:
            pretty: 1

Development specific settings include logging to console instead of file. Logging output is also in more detail for debugging. JSON output for the API is also expanded with pretty print.

production.yml

This file defines Dancer2 directives which apply to the production environment.

~/app/environments (master) $ cat production.yml              
logger: 'File'
log_level: 'info'
show_errors: 0
warnings: 0
engines:
    logger:
        File:
            log_dir: '/var/log/rendmap'
            file_name: 'api.log'

Production specific settings include logging to a file. Logging output is in less detail than development. The log file location is set to /var/log/rendmap/api.log, but can be changed to any location or filename.

additional service configs

Additionally, a sample httpd.conf and systemd service file are included within the app directory to setup in a production environment. Path and user details will need to be updated accordingly before using both.

DATABASE

The schema.sql file located within the db directory can be used to create the database schema required for this application.

~/db (master) $ mysql database_name < schema.sql

RUNNING THE PROJECT

The project can be run during development using the development script located with the app dir of the project. A webserver will be spawned on port 5000, using the development environment settings as defined in the development.yml file.

~/app (master) $ ./development 
HTTP::Server::PSGI: Accepting connections at http://0:5000/
127.0.0.1 - - [23/Jul/2018:10:01:53 -0500] "GET /api/points HTTP/1.1" 200 2783 "-" "curl/7.52.1"
127.0.0.1 - - [23/Jul/2018:10:03:23 -0500] "POST /api/point HTTP/1.1" 403 12 "-" "curl/7.52.1"

The development server is run with plackup using the Shotgun loader. The Shotgun loader delays the compilation and execution of the application until runtime, which means changes to any code within the project don’t require restarting the app. Of note, there is a significant performance cost to running the application with the Shotgun loader and isn’t recommended for production environments.

HTTP METHODS AND ROUTES

options /points

This method returns the Allow header indicating which methods are available for the points endpoint.

PARAMETERS

None.

RETURNS

The Allow header indicating GET and OPTIONS are available methods.

$ curl -sD - -X OPTIONS server:5000/api/points
HTTP/1.0 200 OK
Date: Wed, 25 Jul 2018 19:51:40 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Allow: GET,OPTIONS
Content-Length: 0
Content-Type: text/html

get /points

This method returns all of the points from the db table. Optional parameters filter the data returned.

PARAMETERS

id

The id matching the point.

point

The string of the GPS coordinate.

description

The string description.

user_id

The user_id who created the points.

RETURNS

JSON datastructure, with ‘points’ key, containing point objects. The objects contain key value pairs of the db table columns and values.

$ curl -sD - -X GET server:5000/api/points
HTTP/1.0 200 OK
Date: Thu, 19 Jul 2018 16:53:00 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Content-Length: 2298
Content-Type: application/json

{
   "points" : [
      {
         "point" : "test point 1",
         "description" : "test description 1",
         "created_at" : "2018-07-06 12:28:44",
         "user_id" : 1,
         "id" : 1
      },
      {
         "created_at" : "2018-07-06 14:01:13",
         "description" : "test description 2",
         "user_id" : 2,
         "point" : "test point 2",
         "id" : 2
      },
   ]
}
$ curl -sD - -X GET server:5000/api/points?user_id=1&description=test
HTTP/1.0 200 OK
Date: Thu, 19 Jul 2018 16:53:00 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Content-Length: 2298
Content-Type: application/json

{
   "points" : [
      {
         "point" : "test point 1",
         "description" : "test",
         "created_at" : "2018-07-06 12:28:44",
         "user_id" : 1,
         "id" : 1
      }
   ]
}

options /point

This method returns the Allow header indicating which methods are available for the point endpoint.

PARAMETERS

None.

RETURNS

The Allow header indicating POST and OPTIONS are available methods.

$ curl -sD - -X OPTIONS server:5000/api/point
HTTP/1.0 200 OK
Date: Wed, 25 Jul 2018 19:51:40 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Allow: POST,OPTIONS
Content-Length: 0
Content-Type: text/html

post /point

This method stores a new point into the db table.

The api-key header containing a value matching what’s stored in the user_keys table, is required to post. 403 ‘unauthorized’ will be returned if the api-key is missing or doesn’t match.

After authentication is successful, a JSON payload containing key value pairs for ‘point’ and ‘description’, are required. 400 ‘bad request’, with string indicating ‘point and description values are required’ will be returned if the payload is missing either.

After verifying point and description, the new point will be inserted into the table, and 200 ‘OK’, with string indicating ‘point was inserted correctly’ will be returned.

PARAMETERS

api-key

The api-key header with value matching what’s stored in the user_keys table.

point

The decimal formatted GPS coordinate of the point to add.

description

The string description of the point to add.

RETURNS

403

403 Forbidden, with string ‘unauthorized’, will be returned if the api-key header is missing or doesn’t match.

$ curl -sD - -X POST server:5000/api/point
HTTP/1.0 403 Forbidden
Date: Fri, 20 Jul 2018 19:48:26 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Content-Length: 12
Content-Type: text/plain

unauthorized

See the 200 RETURN example below for a complete example containing the api-key header.

400

400 Bad Request, with string ‘point and description values are required’, will be returned if the request is missing the point and description keys in the JSON payload.

$ curl -sD - -X POST -H 'API-KEY: 1234567890qwerty' server:5000/api/point
HTTP/1.0 400 Bad Request
Date: Fri, 20 Jul 2018 19:59:12 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Content-Length: 41
Content-Type: text/plain

point and description values are required

See the 200 RETURN example below for a complete example containing the correct payload..

200

200 OK, with string ‘point was inserted correctly’, will be returned if the request contains all of the required parts as descripted above.

$ curl -sD - -X POST -H 'API-KEY: 1234567890qwerty' -d '{"point":"test point","description":"test description"}' server:5000/api/point
HTTP/1.0 200 OK
Date: Fri, 20 Jul 2018 19:58:35 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Content-Length: 28
Content-Type: text/plain

point was inserted correctly

options /maps

This method returns the Allow header indicating which methods are available for the maps endpoint.

PARAMETERS

None.

RETURNS

The Allow header indicating GET and OPTIONS are available methods.

$ curl -sD - -X OPTIONS server:5000/api/maps
HTTP/1.0 200 OK
Date: Wed, 25 Jul 2018 19:51:40 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Allow: GET,OPTIONS
Content-Length: 0
Content-Type: text/html

get /maps

This method returns all of the maps from the db table. Optional parameters filter the data returned.

PARAMETERS

id

The id matching the point.

name

The string name.

description

The string description.

user_id

The user_id who created the maps.

RETURNS

JSON datastructure, with ‘maps’ key, containing map objects. The objects contain key value pairs of the db table columns and values.

$ curl -sD - -X GET server:5000/api/maps
$ curl -sD - -X GET server:5000/api/maps?user_id=1&description=test

options /map

This method returns the Allow header indicating which methods are available for the map endpoint.

PARAMETERS

None.

RETURNS

The Allow header indicating POST and OPTIONS are available methods.

$ curl -sD - -X OPTIONS server:5000/api/map
HTTP/1.0 200 OK
Date: Wed, 25 Jul 2018 19:51:40 GMT
Server: HTTP::Server::PSGI
Server: Perl Dancer2 0.206000
Allow: POST,OPTIONS
Content-Length: 0
Content-Type: text/html

post /map

This method stores a new map into the db table.

PARAMETERS

api-key

The api-key header with value matching what’s stored in the user_keys table.

name

The string name of the map to add.

description

The string description of the map to add.

RETURNS

403

403 Forbidden, with string ‘unauthorized’, will be returned if the api-key header is missing or doesn’t match.

$ curl -sD - -X POST server:5000/api/map

See the 200 RETURN example below for a complete example containing the api-key header.

400

400 Bad Request, with string ‘name and description values are required’, will be returned if the request is missing the name and description keys in the JSON payload.

$ curl -sD - -X POST -H 'API-KEY: 1234567890qwerty' server:5000/api/map

See the 200 RETURN example below for a complete example containing the correct payload.

200

200 OK, with string ‘map was inserted correctly’, will be returned if the request contains all of the required parts as descripted above.

$ curl -sD - -X POST -H 'API-KEY: 1234567890qwerty' -d '{"name":"test point","description":"test description"}' server:5000/api/map

This software is available under the MIT license.

Copyright © 2018 Blaine Motsinger

AUTHOR

Blaine Motsinger blaine@renderorange.com