Bored API Quick Start Guide

This blog documents the Bored API created by Drew Thoennes and hosted on https://www.boredapi.com. For the original documentation of this project, click this documentation link and visit its README on GitHub.

Readers are expected to have some knowledge of web APIs. If not, please refer to my earlier blog A Beginner’s Guide to APIs.

What is the Bored API?

The Bored API is a public web API where you submit queries and the API returns suggested things to do. You can narrow down the scope of suggestions by specifying certain criteria such as activity type or number of participants. If you do not specify any criteria, you will get a random suggestion.

Authentication and authorization

You do not need an API key or any username/password to use this API.

Installation and deployment

The Bored API was developed using MEVN stack with frontend using Vue.js and Webpack and backend using Node.js and MongoDB. The API application on www.boredapi.com is hosted on Heroku. You can use this hosted API for querying activities without deploying your own.

If you do want to install and deploy this project on your own host, follow the steps below:

1. Install Node.js and install MongoDB.
2. Clone the project from https://github.com/drewthoennes/Bored-API.

3. Start a MongoDB instance, change the directory to the cloned project from step 2 and run

    npm install
    npm start
   

4. The Bored API starts on https://hostname:8080.

Endpoints

This API supports HTTP GET on the endpoint: /api/activity. Refer to a separate interactive document called Bored Swagger UI for details on the endpoint and available parameters¹.

Example response

Here is an example Json response you may get from this API:

{ "activity": "Learn how the internet works",
  "type": "education",
  "participants": 1,
  "price": 0,
  "link": "",
  "key": "9414706",
  "accessibility": 0.1
}

where

Use cases

The Bored API has been used in other applications including

• I’m Bored Alexa skill
• Python wrapper
• Kotlin wrapper
• React app
• Vue app
• iOS app
• Are you bored web app

Miscellaneous items to discuss with the developer (if I had a chance)

1. HTTP response status code

Currently, the API does not return HTTP response status code 404 for result not found. For example, when I run the curl command below

  curl https://www.boredapi.com/api/activity?price=1

I get "error": "No activity found with the specified parameters" in the Json response. If I curl the header

  curl -I https://www.boredapi.com/api/activity?price=1

The returned header shows HTTP status 200. I think having a return status code 404 for not found probably is more conventional and appropriate in this case.

2. Potential future feature suggestions

• Currently the only HTTP method available is GET. What if we allowed users to post new activity suggestions in a “segregated” manner? For example, the existing activity entries will be tagged with a new attribute status=official and future user-submitted activities will be assigned status=user-submitted. Once in a while the API administrator may go through the suggestions and update the status from user-submitted to official for any interesting new suggestions. We will support HTTP POST and maybe even PUT or DELETE for user-submitted items. To have control over random user submissions or deletions, we probably need to implement API authentication. For the GET method, it will continue to be authentication-free and the new status attribute will be made available as an additional parameter users can query on.
• Currently only Json response is available. We can provide other response types such as txt, yaml, or xml.
• Allow querying for multiple activities in one attempt.

3. The accessibility parameter

The term accessibility can be a bit misleading. At first I thought it meant whether the activity was friendly to people with disabilities. I suggest a more straightforward term such as difficulty.

Special thanks to Drew for developing and sharing this interesting web API publicly.