/api_bun

🥖 A tasty fast fake API for developers and teachers... made with bun

Primary LanguageTypeScript

🥖 API bun

Note

An API server for rapid prototyping, testing, workshops...

Delicious JSON fast food ready to consume.

This project was cooked using bun v1.1.3.

  • 🥖 Just-in-memory or file-based
  • 🥖 Open or secured
  • 🥖 For rapid prototypes
  • 🥖 For front end testing
  • 🥖 For educational purposes

1 🍳 Ready for lunch launch

# ⬇️ clone the repo
git clone https://github.com/AlbertoBasalo/api_bun.git
cd api_bun

1.1 🧑‍🍳 - If you have already bun in your system

# 🥖 want to taste this!
bun run start
# 🧑‍🍳 To cook in dev mode:
# install the tools...
bun i
# and then run-watching changes.
bun run dev

1.2 🍽️ - If not a bun user, then fallback to npm

Tip

Bun installation is easy and highly recommended.

https://bun.sh/docs/cli/install

# 🥖 want to taste this!
# install local bun...
npm run bun:i
# and then start the API server with npm
npm start

2 🧂 Tasty environment configuration

API-bun is configurable through the command line, .env file, or code defaults. To get an idea of your flavors, see configuration types and the .env sample below.

export type ApiBunConfig = {
  /** Log level (info,none,verbose) */
  LOG_LEVEL: LogLevels;
  /** Storage type (memory,file) */
  STORAGE: StorageTypes;
  /** Security type (none,write) */
  SECURITY: SecurityTypes;
  /** Secret */
  SECRET: string;
};

Tip

Sample .env with default values

Create it outside the src folder. It will be ignored by git.

STORAGE=memory
LOG_LEVEL=info
SECURITY=none
SECRET=secret

3 🥡 Storage

3.1 🍱 In Memory

By default, the API-bun uses an in-memory storage system for rapid prototyping and testing. This means that all data is lost when the server stops. Useful for clean starts.

If you want to feed the system with some seed data, just create a file named db/{collection_name}.json with an array of objects. Api-bun will load it automatically and serve it fresh without touching nothing.

As any usable example, you can find :

  • a db/activities.json file with a list of recreational activities.
  • a db/categories.json file with a list of categories for an store.
  • a db/products.json file with a list of products for an store.

Also you can taste flavors of the world by using the amazing countries-states-cities-database files.

3.2 🍲 File System

If you want to persist changes between server restarts, then configure the .env file with STORAGE=file. This will save all changes to the file system in the db folder. Useful for after test analysis or to run in a more realistic scenario.

4 🍵 Security

4.1 🍩 None

The default security level is none. This means that the API-bun will not require any token to access the resources. Again, this is useful for rapid prototyping and testing, the main goal of this project.

4.2 🍪 Signed Token for write

If you want to add a minimal security layer, then configure the .env file with SECURITY=write. This will require a signed token to access the resources. The token is generated with the SECRET value in the .env file.

When enabled, any POST, PUT, PATCH or DELETE request to the API must include the token in the Authorization header with the Bearer prefix.

The identified user id is also added to any posted item as userId property as an owner for future fine grained security.

Caution

The token is not JWT compliant and is only a minimal security layer.

To register a new user

curl -X POST http://localhost:3000/api/register -d '{"email":"admin@world.org","password":"1234"}' -H "Content-Type: application/json"

To login

curl -X POST http://localhost:3000/api/login -d '{"email":"admin@world.org","password":"1234"}' -H "Content-Type: application/json"

5 🍕 API endpoints

5.1 🍟 Get data

# get all activities
http://localhost:3000/api/activities
# get one activity
http://localhost:3000/api/activities/1
# get activities by key/value
http://localhost:3000/api/activities?key=slug&value=standup-surfing_laco-di-como_2023-08-01
# get by content
http://localhost:3000/api/activities?q=surf

6 🍔 Forced responses

When testing your app, sometimes you want to force the API to return a specific response. This can be done by adding some query parameter to the request.

6.1 🍟 Forced status codes

To force a specific status code, add the status query parameter to the request.

curl -X GET http://localhost:3000/api/activities?status=404

6.2 🍕 Forced delay

To force a delay in the response, add the delay query parameter to the request. The value is in milliseconds.

curl -X GET http://localhost:3000/api/activities?delay=5000

X 🥪 Hot features and cold road-map

  • Publishes a generic CRUD API
  • Endpoint routes in the form http://localhost:3000/api/{collection_name} for GET all or POST.
  • Add the id http://localhost:3000/api/{collection_name}/{id} for GET one, PUT or DELETE.
  • Add queryParams http://localhost:3000/api/{collection_name}?key={key}&value={value} for GET by key/value.
  • Always try to feeds any resource with seed data from db/{collection_name}.json.
  • If no file found, then starts with an empty array.
  • Uses id as a primary key to identify items.
  • If not supplied during POST, then generates a new random id.
  • Configuration with .env file or command line (see below).
  • If configured with STORAGE=file, then persist changes (POST,PUT, DELETE) to file system.
  • PUT works like a PATCH, only updating the fields supplied.
  • Logs to console with different levels (info, none, verbose).
  • Minimal security with signed token (not JWT compliant).
  • JWT Security and authorization
  • Clear an endpoint when DELETE to the endpoint root
  • Sorted results
  • Pagination
  • Put and patch distinction
  • Allow to configure the root api route
  • Allow to configure the primary key property name
  • Allow to configure the storage path
  • Published to npm

Caution

Not suitable for production use. Use only for rapid prototyping, testing, workshops...

🧑🏼‍💻 By Alberto Basalo

twitter albertobasalo

git albertobasalo