Hapcat Server API¶

GET /¶

Dump the routes for debugging.

GET /api/serverinfo/¶

Redirect to the latest API version serverinfo.

Status Codes:	302 Found – Redirect

Example request:

http

GET /api/serverinfo/ HTTP/1.0

curl

curl -i http://nohost/api/serverinfo/

Example response:

HTTP/1.0 302 FOUND
Location: http://localhost:8080/api/v0/serverinfo/

POST /api/v(int: version)/addlocation/¶

POST /api/v(int: version)/addevent/¶

Add an event or location.

Request Headers:
	Authorization – The JWT authorization token for the user from `POST /api/v(int:version)/auth/`.
Query Parameters:
	version – The version of the API currently in use.
Request JSON Object:
	type (string) – `event` or `location`. name (string) – The name of the event or location. address (string) – The address. tags (photos) – A list of tag UUIDs. tags – A list of photo URLs.
Response JSON Object:
	success (boolean) – `True` or `False` message (string) – A message if failed. votable – The new event or location. See the documentation for `GET /api/v(int:version)/location/(location)` and `GET /api/v(int:version)/event/(event)` for details on the format.
Status Codes:	200 OK – No error 400 Bad Request – Invalid request.

Example request:

http

POST /api/v0/addevent/ HTTP/1.0
Accept: application/json
Content-Type: application/json
Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbG...0UHGO-U0R4PTQ

{
    "type": "event",
    "name": "Event name",
    "address": "2345 Tourist Road, Bla OH",
    "tags": [
        "d927d94f-beb8-4295-ac78-5c00e6dc217c",
        "bd6b3a7e-d967-4c96-beb2-ecb10dfe72fb"
    ],
    "photos": [
        "http://example.com/image.png"
    ]
}

curl

curl -i -X POST http://nohost/api/v0/addevent/ -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbG...0UHGO-U0R4PTQ' --data-raw '{"address": "2345 Tourist Road, Bla OH", "name": "Event name", "photos": ["http://example.com/image.png"], "tags": ["d927d94f-beb8-4295-ac78-5c00e6dc217c", "bd6b3a7e-d967-4c96-beb2-ecb10dfe72fb"], "type": "event"}'

Example success:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "success": true,
    "votable": {
        "id": "f99d4246-f354-49ca-9a4b-d568861ac3c9",
        "name": "Event name",
        "location": "ea72c24b-afdd-448e-b822-2c6646ca90fc",
        "tags": [
            "d927d94f-beb8-4295-ac78-5c00e6dc217c",
            "bd6b3a7e-d967-4c96-beb2-ecb10dfe72fb"
        ],
        "type": "event",
        "photos": [
            "http://example.com/image.png"
        ]
    }
}

Example failure:

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "success": false,
    "message": "Invalid tag"
}

GET /api/v(int: version)/event/(event)¶

Get the given event’s info.

Query Parameters:
	version – The version of the API currently in use event – The UUID of the event to get info for
Status Codes:	200 OK – Success 400 Bad Request – Invalid event ID
Response JSON Object:
	id (UUID) – The event ID name (string) – The tag name location (UUID) – The raw location this event takes place at type (string) – `event` tags – The tag IDs for this event

Example request:

http

GET /api/v0/event/b0a28a40-b8ad-4131-8c64-071f3fd45bee HTTP/1.0
Accept: application/json

curl

curl -i http://nohost/api/v0/event/b0a28a40-b8ad-4131-8c64-071f3fd45bee -H 'Accept: application/json'

Example success:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "id": "b0a28a40-b8ad-4131-8c64-071f3fd45bee",
    "name": "The Accidentals - Concert at the Kent Stage",
    "location": "cbedf9e2-4a1a-44b9-9e3f-6fe870405329",
    "tags": [
        "64b9eae5-b220-4a57-92f4-c21dc9b19ec5",
        "71f450ef-b344-45f3-9b60-0dbda7fce2f0",
        "f8ddde82-331e-43c2-a2fd-985c5eb8fe52"
    ],
    "type": "event"
}

Example failure:

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "status": "failure",
    "message": "Invalid event ID"
}

GET /api/v(int: version)/location/(location)¶

Get the given location’s info.

Query Parameters:
	version – The version of the API currently in use location – The UUID of the location to get info for
Status Codes:	200 OK – Success 400 Bad Request – Invalid location ID
Response JSON Object:
	id (uuid) – The location ID. address (string) – The location address. ephemeral (boolean) – If true, this location is just an address for events. name (string) – The location name if not ephemeral. tags – The tag IDs for this location if not ephemeral. type (string) – `rawlocation` or `location`.

Example request:

http

GET /api/v0/location/a25a1b9a-2f5a-4c76-b19f-eb970d2c7049 HTTP/1.0
Accept: application/json

curl

curl -i http://nohost/api/v0/location/a25a1b9a-2f5a-4c76-b19f-eb970d2c7049 -H 'Accept: application/json'

Example success, normal location:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "id": "a25a1b9a-2f5a-4c76-b19f-eb970d2c7049",
    "address": "1444 E Main St, Kent, OH 44240",
    "name": "Hungry Howie's Pizza",
    "ephemeral": false,
    "tags": [
        "17b20e68-8cde-4bc3-91a2-f5926a3e2b0f",
        "0e858a8b-cd18-4617-8a94-2a8bab4945a9",
        "d6f2989d-d5c0-477d-a8a4-d22e47087ab2"
    ]
}

Example success, raw/ephemeral location:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "id": "cbedf9e2-4a1a-44b9-9e3f-6fe870405329",
    "address": "175 E Main St, Kent, OH 44240",
    "ephemeral": true
}

Example failure:

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "status": "failure",
    "message": "Invalid location ID"
}

POST /api/v(int: version)/login/¶

POST /api/v(int: version)/auth/¶

Login.

Query Parameters:
	version – The version of the API currently in use.
Request JSON Object:
	username (string) – The login username. password (string) – The user’s password.
Response JSON Object:
	success (boolean) – `True` or `False`. message (string) – A message if success is `False`. access_token (string) – The access token for future requests.
Status Codes:	200 OK – Success 401 Unauthorized – Invalid credentials.

Example request:

http

POST /api/v0/login/ HTTP/1.0
Accept: application/json
Content-Type: application/json

{
    "username": "user",
    "password": "pass"
}

curl

curl -i -X POST http://nohost/api/v0/login/ -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"password": "pass", "username": "user"}'

Example success:

Note that the access token is truncated here.

HTTP/1.0 200 OK
Content-Type: application/json

{
    "success": true,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJ...8QWJFcYlI"
}

Example failure:

HTTP/1.0 401 UNAUTHORIZED
Content-Type: application/json

{
    "success": false,
    "message": "Invalid credentials"
}

POST /api/v(int: version)/register/¶

POST /api/v(int: version)/registration/¶

Register the given user.

Query Parameters:
	version – The version of the API currently in use.
Request JSON Object:
	username (string) – The requested username. email (string) – The user’s email address. date_of_birth – The user’s date of birth. password (string) – The user’s password.
Response JSON Object:
	status (string) – `success` or `failure`. username (string) – The username. message (string) – An optional message on failure.
Status Codes:	200 OK – Success 400 Bad Request – Insufficient password strength. 409 Conflict – The username is already taken.

Example request:

http

POST /api/v0/registration/ HTTP/1.0
Accept: application/json
Content-Type: application/json

{
    "username": "user",
    "password": "password",
    "email": "user@example.com",
    "date_of_birth": {
        "year": 1999,
        "month": 9,
        "day": 9
    }
}

curl

curl -i -X POST http://nohost/api/v0/registration/ -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"date_of_birth": {"day": 9, "month": 9, "year": 1999}, "email": "user@example.com", "password": "password", "username": "user"}'

Example success:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "status": "success",
    "username": "user"
}

Example failures:

HTTP/1.0 409 CONFLICT
Content-Type: application/json

{
    "status": "failure",
    "username": "user",
    "message": "Username already exists"
}

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "status": "failure",
    "username": "user",
    "message": "Insufficiently secure password",
    "details": {
        "warning": "This is a top-10 common password.",
        "suggestions": [
            "Add another word or two. Uncommon words are better."
        ]
    }
}

GET /api/v(int: version)/serverinfo/¶

Get the server info.

Query Parameters:
	version – The version of the API currently in use
Response JSON Object:
	server_version (string) – The version of the backend api_versions (list(int)) – The supported API versions
Status Codes:	200 OK – No error

Example request:

http

GET /api/v0/serverinfo/ HTTP/1.0
Accept: application/json

curl

curl -i http://nohost/api/v0/serverinfo/ -H 'Accept: application/json'

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "server_version": "0.0.2.dev10",
    "api_versions": [
        0
    ]
}

GET /api/v(int: version)/suggestions/¶

Send our suggestions.

Query Parameters:
	version – The version of the API currently in use
Response JSON Object:
	tags – The tags, by ID. See the documentation for `GET /api/v(int:version)/tag/(tag)`. locations – The locations, by ID. See the documentation for `GET /api/v(int:version)/location/(location)`. events – The events, by ID. See the documentation for `GET /api/v(int:version)/event/(event)`. order – The order of the suggestions
Status Codes:	200 OK – No error

Example request:

http

GET /api/v0/suggestions/ HTTP/1.0
Accept: application/json

curl

curl -i http://nohost/api/v0/suggestions/ -H 'Accept: application/json'

Example response:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "tags": {
        "d927d94f-beb8-4295-ac78-5c00e6dc217c": {
            "id": "d927d94f-beb8-4295-ac78-5c00e6dc217c",
            "name": "healthy"
        }
        "64b9eae5-b220-4a57-92f4-c21dc9b19ec5": {
            "id": "64b9eae5-b220-4a57-92f4-c21dc9b19ec5",
            "name": "concert"
        },
    },
    "locations": {
        "f8293fe1-d439-4a4d-ac84-5e8290a28c23": {
            "address": "1075 Risman Dr, Kent, OH 44242",
            "tags": [
                "d927d94f-beb8-4295-ac78-5c00e6dc217c",
            ],
            "id": "f8293fe1-d439-4a4d-ac84-5e8290a28c23",
            "name": "Fresco",
            "photos": [
                "https://media-cdn.tripadvisor.com/media/photo-s/03/2b/02/a1/fresco-mexican-grill.jpg"
            ]
        }
        "cbedf9e2-4a1a-44b9-9e3f-6fe870405329": {
            "address": "175 E Main St, Kent, OH 44240",
            "ephemeral": true,
            "id": "cbedf9e2-4a1a-44b9-9e3f-6fe870405329"
        },
    },
    "events": {
        "b0a28a40-b8ad-4131-8c64-071f3fd45bee": {
            "location": "cbedf9e2-4a1a-44b9-9e3f-6fe870405329",
            "id": "b0a28a40-b8ad-4131-8c64-071f3fd45bee",
            "name": "The Accidentals - Concert at the Kent Stage",
            "photos": [
                "https://image-ticketfly.imgix.net/00/02/83/80/81-og.jpg"
            ],
            "tags": [
                "64b9eae5-b220-4a57-92f4-c21dc9b19ec5",
            ]
        }
    },
    "order": [
        {
            "section": "locations",
            "id": "f8293fe1-d439-4a4d-ac84-5e8290a28c23"
        },
        {
            "section": "events",
            "id": "b0a28a40-b8ad-4131-8c64-071f3fd45bee"
        }
    ]
}

GET /api/v(int: version)/tag/(tag)¶

Get the given tag’s info.

Query Parameters:
	version – The version of the API currently in use tag – The UUID of the tag to get info for
Status Codes:	200 OK – Success 400 Bad Request – Invalid tag ID
Response JSON Object:
	id (UUID) – The tag ID name (string) – The tag name type (string) – `tag`

Example request:

http

GET /api/v0/tag/d927d94f-beb8-4295-ac78-5c00e6dc217c HTTP/1.0
Accept: application/json

curl

curl -i http://nohost/api/v0/tag/d927d94f-beb8-4295-ac78-5c00e6dc217c -H 'Accept: application/json'

Example success:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "id": "d927d94f-beb8-4295-ac78-5c00e6dc217c",
    "name": "healthy",
    "type": "tag"
}

Example failure:

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "status": "failure",
    "message": "Invalid tag ID"
}

GET /api/v(int: version)/vote/(votable)/¶

Vote for an event or location.

Request Headers:
	Authorization – The JWT authorization token for the user from `POST /api/v(int:version)/auth/`.
Query Parameters:
	version – The version of the API currently in use. votable – The UUID of the event or location to vote for.
Response JSON Object:
	success (boolean) – `True` or `False`. message (string) – The failure reason if `False`. votable (string) – The UUID of the event or location voted for. user_id (string) – The UUID of the user. username (string) – The username of the user. numvotes (int) – The total number of votes of this user for this event or location.
Status Codes:	200 OK – Success. 400 Bad Request – Invalid votable ID or user. 401 Unauthorized – Invalid authorization token.

Example request:

http

GET /api/v0/vote/c43e3c6a-64ad-4cc8-94cd-65d1c8e4ada6/ HTTP/1.0
Accept: application/json
Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbG...0UHGO-U0R4PTQ

curl

curl -i http://nohost/api/v0/vote/c43e3c6a-64ad-4cc8-94cd-65d1c8e4ada6/ -H 'Accept: application/json' -H 'Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbG...0UHGO-U0R4PTQ'

Example success:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "success": true,
    "votable": "c43e3c6a-64ad-4cc8-94cd-65d1c8e4ada6",
    "user_id": "e7d45044-d500-451a-825f-cbff616030f2",
    "username": "user",
    "numvotes": 11
}

Example failure:

HTTP/1.0 400 BAD REQUEST
Content-Type: application/json

{
    "success": false,
    "message": "No such votable",
    "votable": "c43e3c6a-64ad-4cc8-94cd-65d1c8e4adaf",
    "user_id": "e7d45044-d500-451a-825f-cbff616030f2",
    "username": "user"
}

GET /debug/dropalldata/¶

Drop all data.

A request to this drops all data in the database.

GET /debug/protectedtest/¶

Test authorization.

Request Headers:
	Authorization – The JWT authorization token for the user from `POST /api/v(int:version)/auth/`.
Response JSON Object:
	id (string) – The user’s UUID. username (string) – The user’s username.
Status Codes:	200 OK – Success. 401 Unauthorized – Invalid authorization token.

Example request:

http

GET /debug/protectedtest/ HTTP/1.0
Accept: application/json
Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbG...0UHGO-U0R4PTQ

curl

curl -i http://nohost/debug/protectedtest/ -H 'Accept: application/json' -H 'Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbG...0UHGO-U0R4PTQ'

Example success:

HTTP/1.0 200 OK
Content-Type: application/json

{
    "id": "4cfab2e4-b38f-435f-b9b1-aa8eb8172dcf",
    "username": "user"
}

Example failure:

HTTP/1.0 401 UNAUTHORIZED
Content-Type: application/json
WWW-Authenticate: JWT realm="Login Required"

{
    "description": "Request does not contain an access token",
    "error": "Authorization Required",
    "status_code": 401
}

GET /debug/reloadtestdata/¶

Load our test data for debugging.

A request to this reloads the test data into the database.

GET /flask-api/static/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.

GET /static/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.