api: http api routes

[ear7h]

POST /api/login

This endpoint is used to issue the bearer tokens which are used for routes that require user authentication.

Two calls to this endpoint are required. The first with the email query parameter, which triggers an email message that will contain a secrete code. This secret code will the be used in the second call in the code parameter (the email parameter is also required for the second call).

Query:

• create - true | false optional. If true, the call to this endpoint will create an account, the account must not exist. If false, the call to this endpoint will only succeed if the account already exists. If not present, an account is created if needed. This parameter is ignored when code is present.
• email - string see above
• code - int see above

Request Body: empty
Response

• first call:
  • 204 No Content - email sent successfully
  • 409 Conflict - if create=true the account already exists. if create=false the account does not exist.
• second call:
  • 200 OK - with the token as a json string "abcd..."
  • 400 Bad Request - the code was invalid

User routes

GET /api/users/self

Get the user data

**Authorization: ** Bearer <token>
Response: the user model for the user in the token

PUT /api/users/self/orgs/:org_id

Adds a favorite org to the user

Authorization: Bearer <token>
Request: None
Response:

• 204 No Content - the org was favorited
• 404 Not Found - the org does not exist

DELETE /api/users/self/orgs/:org_id

Removes a favorite org from the user

Authorization: Bearer <token>
Request: None
Response:

• 204 No Content - the org was unfavorited
• 404 Not Found - the org does not exist

PUT /api/users/self/events/:event_id

Adds a favorite event to the user

Authorization: Bearer <token>
Request: None
Response:

• 204 No Content - the event was favorited
• 404 Not Found - the event does not exist

DELETE /api/users/self/events/:event_id

Removes a favorite event from the user

Authorization: Bearer <token>
Request: None
Response:

• 204 No Content - the event was unfavorited
• 404 Not Found - the event does not exist

event routes

GET /api/events

Query:

• orgs - comma separated list of int, all returned events must be part of one of these orgs.
• tags - comma separated string, all returned events must have at least one matched tag
• before - ISO formatted date (ex. 2020-11-12), all returned events must start before this date
• after - ISO formatted date (ex. 2020-11-12), all returned events must end after this date
• limit - int, the number of responses
• offset - int, the number of responses to skip.

Response

• 200 OK - a JSON list of event models
• 400 Bad Request - incorrect query formatting

GET /api/events/trending

Get events sorted by trending
Response

• 200 OK - a JSON list of event models

GET /api/events/:id

This endpoint returns the event with the given ID

Response

• 200 OK - A single event model
• 404 Not Found - the event with the id does not exist

org routes

GET /api/orgs

Query:

• tags - comma separated string, all returned orgs must have at least one matched tag
• limit - int, the number of responses
• offset - int, the number of responses to skip.

Response

• 200 OK - A list of org models
• 400 Bad Request - incorrect query formatting

GET /api/orgs/:id

This endpoint returns the event with the given ID

Response

• 200 OK - A single event model
• 404 Not Found - the event with the id does not exist

POST /api/orgs/:org_id

Update the org profile

Authorization: Bearer <token>
Request: an org model (IDs and meta fields like created are ignored when stored in the database).
Response

• 200 OK - the org was successfully updated, the new org model is returned
• 400 Bad Request - the request had improperly formatted json

POST /api/orgs/:org_id/events/

Add a new event hosted by the org

Authorization: Bearer <token>
Request: an event model (IDs and meta fields like created are ignored when stored in the database).
Response:

• 200 OK - the event was successfully created, the event with IDs and meta fields is returned
• 400 Bad Request - the request had improperly formatted json
• 403 Forbidden - the token is not granted permission to execute this action

PUT /api/orgs/:org_id/events/:event_id

Update an existing event

Authorization: Bearer <token>
Request: an event model (IDs and meta fields like created are ignored when stored in the database).
Response:

• 200 OK - the event was successfully updated, the event with IDs and meta fields is returned
• 400 Bad Request - the request had improperly formatted json
• 404 Not Found - the event_id does not exist

DELETE /api/orgs/:org_id/events/:event_id

Delete the event

Authorization: Bearer <token>
Response

• 200 OK - the event was successfully deleted
• 404 Not Found - the event_id was invalid

POST /api/orgs/:org_id/events/:event_id/announcements

Add an announcement to an event
Authorization: Bearer <token>
Request: an announcement model (IDs and meta fields like created are ignored when stored in the database).
Response:

• 200 OK - the event announcement was successfully created, the announcement with IDs and meta fields is returned
• 400 Bad Request - the request had improperly formatted json
• 404 Not Found - the event_id does not exist

PUT /api/orgs/:org_id/events/:event_id/announcements/:announcement_id

Update an existing event announcement

Authorization: Bearer <token>
Request: an announcement model (IDs and meta fields like created are ignored when stored in the database).
Response:

• 200 OK - the event announcement was successfully updated, the event with IDs and meta fields is returned
• 400 Bad Request - the request had improperly formatted json
• 404 Not Found - the event_id or the announcement_id was invalid

DELETE /api/orgs/:org_id/events/:event_id/:announcement_id

Delete the event announcement

Authorization: Bearer <token>
Response

• 200 OK - the event annoucement was successfully deleted
• 404 Not Found - the event_id or the announcement_id was invalid

[ear7h]

For all methods the following responses are also possible

• 500 Internal Server Error - the server contains a bug that needs to be fixed

For all authenticated methods, the following responses are possible:

• 403 Forbidden - the token is not granted permission to execute this action
• 401 Unauthorized - the token was not provided or was invalid/outdated (the UI should immediately purge all user data from memory, and redirect to a login page)