Duck backend

Version 1.0.1
Simple Duck sighting backend for having fun.

Requirements

Requires Node.js installed with npm.
Tested with Node.js version 4.2.6, npm v3.10.8 and PostgreSQL 9.5.5 on x86_64-pc-linux-gnu.
Uses Knex which is limited to Postgres, MSSQL, MySQL, MariaDB, SQLite3, and Oracle databases:
http://knexjs.org/

Install

$ git clone https://github.com/tahv0/duck-be.git
$ cd duck-be
$ npm install

Setup database

Setup your PostgreSQL (or other).
Create new account and alter password (or some key) for it.
Create new database and give select, insert and update rights for your user.
Add your database url, port, database name, user and password in knexfile.js

To migrate db run

$ gulp migrate

To populate db run

$ gulp populate

Run

To start server run

$ gulp serve

or if you want to run server in some other port than default 8081

$ gulp serve --port <port>

where you should replace <port> with wanted port number i.e. 3000.

API

List of all RESTful API methods that currently implemented.

Sightings

Get all stored sightings

• URL: /sightings
• METHOD: GET
• Succeeded request:

  • Example request:

    $ curl http://localhost:8081/sightings
    

  • Code: 200

  • Content:

    [
      {
        "id": 1,
        "species": "gadwall",
        "description": "All your ducks are belong to us",
        "dateTime": "2016-09-30T22:01:00.000Z",
        "count": 1
      },
      ...
    ]
    
    

Species

List of all stored species.

• URL: /species
• METHOD: GET
• Succeeded request:

  • Example request:

    $ curl http://localhost:8081/species
    

  • Code: 200

  • Content:

    [
      {
        "name": "mallard"
      },
      ...
    ]
    
    

Post new Sighting

Update single Sighting. One cannot change Id.

• URL: /sightings/:id
• METHOD: PATCH
• BODY PARAMETERS:
  • MANDATORY:
    • species: string I.e redhead. Filters Sightings by Specie.
    • count: integer. Defines min count that single Sighting has to have.
  • OPTIONAL:
    • dateTime: timestamp in ISO8601 format
    • description: string
• Succeeded request:

  • Example request:

    $ curl -H "Content-Type: application/json" -X POST -d '{"species":"mallard", "description":"Kwaak kwaak", "count": 66}' http://localhost:8081/sightings        
    

  • Code: 200

  • Content:

    {
      "species": "mallard",
      "description": "Kwaak kwaak",
      "count": 66,
      "dateTime": "2017-02-19T11:10:56.474Z",
      "id": 13
    }
    

Get Sightings by Id

Get single Sighting by Id

• URL: /sightings/:id
• METHOD: GET
• Succeeded request:

  • Example request:

    $ curl http://localhost:8081/sightings/5
    

  • Code: 200

  • Content:

    {
      "id": 5,
      "species": "redhead",
      "description": "I think this one is called Alfred J.",
      "dateTime": "2016-11-29T08:00:01.000Z",
      "count": 1
    }
    

Update Sighting's informations by Id

Update single Sighting. One cannot change Id.

• URL: /sightings/:id
• METHOD: PATCH
• OPTIONAL PARAMETERS: dateTime
• Succeeded request:

  • Example request:

    $ curl -H "Content-Type: application/json" -X PATCH -d '{"species":"redhead", "description":"Kwaak kwaak", "count": 3 }' http://localhost:8081/sightings/13
    

  • Code: 200

Delete Sighting by Id

Delete single Sighting.

• URL: /sightings/:id
• METHOD: DELETE
• Succeeded request:

  • Example request:

    $ curl -X DELETE http://localhost:8081/sightings/13
    

  • Code: 200

Get report

Get list of Sighting based on request parameters (JSON).

• URL: /sightings/report
• METHOD: GET
• URL parameters:
  • Mandatory: month and year or startTime and endTime but not both!
    • year: integer
    • month: integer
    • startTime: timestamp in ISO8601 format. I.e 2017-02-17T15:05:52.088Z
    • endTime: timestamp in ISO8601 format. I.e 2017-02-17T15:05:52.088Z. Has to be bigger than startTime
  • Optional: count and species parameters
    • species: string I.e redhead. Filters Sightings by Specie.
    • count: integer. Defines min count that single Sighting has to have.
• Succeeded request

  • Example requests:

    $ curl http://localhost:8081/sightings/report
    

    
    # Get report with some minimum count that Sightings has to have
    $ curl http://localhost:8081/sightings/report?count=44
    

    # Get report by specific Month
    $ curl -v -L "http://localhost:8081/sightings/report?year=2016&month=12"
    $ curl -v -L "http://localhost:8081/sightings/report?year=2016&month=12&count=2"
    

    # Get reports by range of startTime and endTime
    $ curl -v -L "http://localhost:8081/sightings/report?startTime=2015-02-19T09:29:36.656Z&endTime=2017-02-19T09:29:36.656Z&count=6"
    

  • Code: 200

  • Content:

    [
      {
        "id": 1,
        "species": "gadwall",
        "description": "All your ducks are belong to us",
        "dateTime": "2016-09-30T22:01:00.000Z",
        "count": 6
      },
      ...
    ]
    

Usage

If you have trouble for sending POST-requests to API remember to add Content-Type: application/json to request headers. This is only content type supported in API.

When adding new sighting, backend automatically generates id-field for sightings. Id is replaced in server if it is provided in POST-request body.