0xorg/0x-api repository overview

⁠Table of contents

• Introduction⁠
• Services⁠
  • HTTP Services⁠
  • Data Services⁠
• Getting started⁠
  • Pre-requirements⁠
  • Developing⁠
• Commands⁠
• Database⁠
• Deployment⁠
• Release⁠
• Legal Disclaimer⁠

⁠Introduction

The 0x API is a collection of services and endpoints that can be run together or separately. In aggregate, the APIs provide interfaces to 0x liquidity, 0x staking data and more. Everything can be run monolithically via yarn start and docker-compose up as described in Getting Started⁠.

⁠Services

The API contains different services that serve a collection of HTTP or websocket endpoints and keep your database in sync with 0x Mesh⁠ and Ethereum state.

⁠HTTP Services

These are services that handle HTTP requests and responses.

⁠Data Services

These are services that make sure the data being served is present and up-to-date by keeping the database in sync with 0x Mesh⁠ and Ethereum. With the exception of the Staking HTTP service, which has a hard dependency on the Staking Event Pipeline⁠, the endpoints above run without these services, but would be providing degraded or non-functional service. There is nothing stateful about 0x API -- all the data comes from 0x Mesh⁠ or the Ethereum blockchain.

⁠Getting started

⁠Pre-requirements

• Node.js⁠ > v8.x
• Yarn⁠ > v1.x
• Docker⁠ > 19.x

⁠Developing

To get a local development version of 0x-api running:

1. Clone the repo.

2. Create an .env file and copy the content from the .env_example file. Defaults are defined in config.ts/config.js. The bash environment takes precedence over the .env file. If you run source .env, changes to the .env file will have no effect until you unset the colliding variables.

1. Install the dependencies:

   yarn
   

   Copy

2. Build the project:

   yarn build
   

   Copy

3. Run docker-compose up to run the other dependencies required for the API. This uses the local docker-compose.yml file. On start-up, the event-pipeline⁠ container will crash and restart until Postgres is up. If you switch CHAIN_ID after a prior run, you will have to rm -rf 0x_mesh postgres to delete the volumes containing stale data.

4. Run the database migrations:

yarn db:migrate

1. Start the API

   yarn start
   

   Copy

   For development:

   yarn dev
   

   Copy

⁠Developing on Ganache

Ganache is supported, but will not contain the same staking data and 0x Mesh liquidity that kovan or mainnet have for example. To use ganache, use the .env file below:

CHAIN_ID=1337
ETHEREUM_RPC_URL=http://ganache:8545

Then run

$ docker-compose up
$ yarn dev

⁠Testing

Run yarn test. It's really that easy :)

Tip: Test suites set up and teardown sandboxed environments, so using .only on it and describe statements will save lots of development time.

⁠Commands

• yarn build - Build the code
• yarn test - Test the code
• yarn lint - Lint the code
• yarn start - Starts the API
• yarn dev - Starts the API in dev-mode
• yarn watch - Watch the source code and rebuild on change
• yarn prettier - Auto-format the code
• yarn release - Release a new version of the 0x-api

⁠Deployment

A Docker image is built and hosted by Dockerhub⁠ every time a change to the master branch occurs. A Docker image is built, pushed and tagged⁠ when a new version is released⁠ as well. Running this image will run 0x API as a monolith, with all its dependencies. You can run any of the services⁠ separately by overriding the Docker command⁠ with the service-specific command when running the container.

When versioning the API, we freeze the old version in a separate branch so that we can deploy patches, and continue to support the old version until it's officially deprecated. Be aware when contributing fixes that you may want to apply the fix to an older version too.

This is a list of endpoints supported by different versions of the API. If an endpoint is not on this list, it is by default pointed to the master branch.

⁠Release

Releases are triggered automatically by the release GitHub action⁠. They can also be triggered manually by using yarn release, which requires a GITHUB_TOKEN⁠ environment variable.

⁠Database

This project uses TypeORM⁠. It makes it easier for anyone to switch out the backing database used by this project. By default, this project uses a PostgreSQL⁠ database.

⁠Legal Disclaimer

The laws and regulations applicable to the use and exchange of digital assets and blockchain-native tokens, including through any software developed using the licensed work created by ZeroEx Intl. as described here (the “Work”), vary by jurisdiction. As set forth in the Apache License, Version 2.0 applicable to the Work, developers are “solely responsible for determining the appropriateness of using or redistributing the Work,” which includes responsibility for ensuring compliance with any such applicable laws and regulations. See the Apache License, Version 2.0 for the specific language governing all applicable permissions and limitations: http://www.apache.org/licenses/LICENSE-2.0⁠