Service directories done right
Example API Output
This is Outpost's public API component.
It's not useful by itself — it depends on a public index built by Outpost. The API it outputs is consumable by Scout and other compatible Open Referral applications.
✨ Full documentation is available here ✨
It's a simple Node.js app which queries information from a MongoDB collection and publishes it as a read-only, rate-limited REST API.
To run it on your machine you need Node.js, npm, nvm (https://github.com/nvm-sh/nvm) and a working MongoDB database with the right indices available on localhost:27017.
See environmental variables below.
It is recommended to use docker but you can choose to run the project locally as well.
# get the code
git clone [email protected]:wearefuturegov/outpost-api-service.git && cd outpost-api-service
# setup env and database variables
cp sample.env .env
# setup
docker compose up -d
# if you need dummy data
docker compose exec app npm run dummy-data
# access the api
open http://localhost:3001/api/v1/services
# access the mongodb
# NB this runs mongo on a non-standard port `27018` in case you have mongo already running, you can change it to `27017` if you would like to
mongo "mongodb://outpost:password@localhost:27018/outpost_api_development"
# stop the application at any time by running
docker compose stop
# remove the running containers by running
docker compose down# create the database on your localhost and run
mongosh .docker/services/mongo/setup-mongodb.js
# you can also run the following to use add the indices on to an existing database
npm run prepare-indicesYou can provide config with a .env file. Run cp sample.env .env to create a fresh one.
The following environmental variables are required.
| Variable | Description | Example | Required? |
|---|---|---|---|
DB_URI |
Mongo database url | mongodb://outpost:password@localhost:27018/outpost_api_development |
Yes |
GOOGLE_API_KEY |
Google API Key | 1234 |
Yes |
DEBUG_LEVEL |
Debug logging level options are: error, warn, info, http, debug | debug |
No |
FORCE_SSL |
Force SSL defaults to false unless this is set to true | true | No |
HOST_PORT |
If running in docker set this to change the exposed port, default is 3000 | 3001 | No |
It is recommended to have an API for each environment, outpost_api_service_geocode_dev, outpost_api_service_geocode_staging and outpost_api_service_geocode_prod.
You will need to enable the Geocode API, no restrictions are needed.
It's suitable for 12-factor hosting like Heroku. It has a Procfile that will make sure the proper MongoDB indices are set up.
Ensure you set FORCE_SSL to true.
We also provide a Docker image if you would like to host the application in a container
We provide scripts to initialise the database once its been created.
docker run -it --rm \
--env-file .env \
-e DB_URI=mongodb://outpost:[email protected]:27018/outpost_api_development \
outpost-api-service:production prepare-collection
docker run -it --rm \
--env-file .env \
-e DB_URI=mongodb://outpost:[email protected]:27018/outpost_api_development \
outpost-api-service:production prepare-indices
docker run -it --rm \
--env-file .env \
-e DB_URI=mongodb://outpost:[email protected]:27018/outpost_api_development \
outpost-api-service:production dummy-datadocker build --pull --rm --no-cache --progress plain -f Dockerfile.production -t outpost-api-service:production .
docker run \
-e FORCE_SSL=false \
-e DB_URI=mongodb://outpost:[email protected]:27018/outpost_api_development \
--env-file .env \
-p 3002:3000 \
--name outpost-api-production \
-d outpost-api-service:production
docker stop outpost-api-production && docker rm outpost-api-production
docker image rm outpost-api-service:productionIt needs the right indices on the MongoDB collection to enable full-text and geo search. Something like:
db.indexed_services.createIndex({ name: "text", description: "text" })
db.indexed_services.createIndex({ "service_at_locations.location.geometry": "2dsphere" })
You can create these two, plus an index of taxonomy slugs, automatically with the npm run prepare-indices command.
npm run test
# or
docker compose exec app npm run test