Quickstart guide#

This is the quick start guide for setting up and running the API locally.

Prerequisites#

Refer to the general setup guide for setting up the prerequisites. Refer to the ‘API’ column in the requirement matrix to know what you need to run this.

Starting up#

Ensure you download, install and set up all prerequisites. Ensure that the Docker daemon is running.
Clone the repository to your computer. Then switch to the cloned directory. If you’re planning to contribute, fork the repo and clone your fork instead.
```
$ git clone https://github.com/WordPress/openverse.git # or your fork
$ cd openverse/
```
If you followed the general setup guide and installed GitHub CLI, you can clone more simply using the gh command.
```
$ gh repo clone WordPress/openverse # or your fork
$ cd openverse/
```
Bring the ingestion server and API up, along with all their dependent services.
```
$ just api/up
```
The api/up recipe orchestrates the following services: cache, db, upstream_db, es, indexer_worker, ingestion_server, web and proxy.

Now you should be able to access the following endpoints:
- the list of ingestion jobs on http://localhost:50281/task
- the API documentation on http://localhost:50280
Load the sample data. This step can take a few minutes to complete.
```
$ just api/init
```
Troubleshooting

If this step fails, cleaning up and restarting usually fixes it.
```
$ just down -v
$ just api/init
```

With the data loaded, the API can now return JSON responses to your HTTP requests.

$ just api/stats
just _curl-get "images/stats/" http://localhost:50280
curl "http://localhost:50280/v1/images/stats/"
[{"source_name":"flickr","display_name":"Flickr","source_url":"https://www.flickr.com","logo_url":null,"media_count":2500},{"source_name":"stocksnap","display_name":"StockSnap","source_url":"https://stocksnap.io","logo_url":null,"media_count":2500}]%

Tip

jq is a tool for parsing and manipulating JSON data. If you have jq installed, you can pipe the response to it and transform it.

$ just api/stats | jq '.[0]'
{
  "source_name": "flickr",
  "display_name": "Flickr",
  "source_url": "https://www.flickr.com",
  "logo_url": null,
  "media_count": 2500
}

$ just api/stats 'audio' | jq '[.[] | .source_name]'
[
  "freesound",
  "jamendo",
  "wikimedia_audio"
]

jq is great, we recommend you download it.

Shutting down#

Refer to the common instructions.