Skip to main content

API

BOMIST provides two APIs: a local one, available on every workspace; and a cloud one, available only on Team Workspaces.

Local API​

The app can launch a local web server that exposes a REST API. This API doesn't run on the cloud. To be able to use it you just need to be logged-in on the app and to enable it from Settings - API.

With the API you can retrieve and process your workspace's data the way you want by creating your own scripts. This is great way to integrate BOMIST with your own systems.

Once the server is running, you can test it by simply opening your web browser at http://localhost:3333. You should get something like this:

{
  "bomist": {
    "version": "2.1.4",
    "user": {
      "email": "user-email"
    },
    "workspace": {
      "team": false,
      "name": "Sample"
    }
  },
  "documentation": "http://localhost:3333/_swagger_ui"
}

Documentation​

The web server not only serves the API but also its documentation through a Swagger UI interface. Once the server is running, the documentation should be accessible at http://localhost:3333/_swagger_ui (assuming you are using the default host and port) .

If you just want to have an idea on how the documentation looks like without having to install or open the app, you can also check it here:

Documentation

This link is not regularly updated though, so make sure you always use the documentation served by the app.

Accessing the API from another computer​

You can access the API from another computer on the same network. When starting the local web server, make sure you bind it to 0.0.0.0 (instead of localhost). Then you'll need to know the local IP address of your computer.

On Windows, you can use the ipconfig command.

$ ipconfig

Ethernet adapter vEthernet (WSL):
   IPv4 Address. . . . . . . . . . . : 123.45.678.1
   Subnet Mask . . . . . . . . . . . : 255.255.240.0

Now from another computer you should be able to query the API.

Assuming the port was set to 3333 (default), you should get something like this:

$ curl 123.45.678.1:3333

{
   "bomist":{
      "app":{
         "version":"2.10"
      },
      "api":{
         "swaggerUI":"http://localhost:3333/_swagger_ui",
         "swaggerJSON":"http://localhost:3333/swagger.json"
      },
      "user":{
         "email":"[email protected]"
      },
      "workspace":{
         "team":false,
         "name":"Sample"
      }
   }
}
Windows Subsystem for Linux (WSL)

When accessing the API from WSL you'll need to follow the steps above, even if the WSL is running on the same computer.

Filtering & querying data​

Most of the GET endpoints allow you to filter data by its fields. Assuming you'd want to get 10 parts from Microchip, or to list parts that have lower than 50 units in stock, this is what you'd do:

GET /parts?part.manufacturer=Microchip&limit=10    # get 10 Microchip parts
GET /parts?part.stock={"$lt": 50}                  # get all parts that have less that 50 units of stock

For most use cases, the /search endpoint might be the most convenient one for querying data though.

An example:

POST /search?limit=10

{
  "selector": {
    "type": "part",
    "part.manufacturer": "Microchip",
    "part.stock": {
      "$lt": 10
    }
  }
}

Supported query operators such as $lt, $gt, $in, $elemMatch or $regex are listed on the pouchdb-find package which the API internally uses: https://www.npmjs.com/package/pouchdb-find

Examples​

Some scripts making use of the API are available on this GitHub repository. If you'd like to see other examples please get in touch.

CORS​

CORS can be configured by setting the environment variable BOMIST_API_CORS, with multiple hosts separated by a comma. An example:

BOMIST_API_CORS=http://localhost:3000,https://mywebpage.com

Make sure the environment variable is set before starting the API server.

Cloud API​

A cloud REST API is provided for Team Workspaces. The TEAM subscription's owner can generate an API key through the dashboard on the website (not on the app). which is used for authentication by passing it as the HTTP header x-api-key.

This API is read-only, providing only endpoints to read data from your Team Workspace. This is particularly suitable to integrate with reporting tools online for example (Microsoft Power BI, Grafana, etc).

Documentation​

You can access the documentation through the following link:

Documentation

The above link can also be used to test the API on your own Team Workspace, provided you set the x-api-key header (look for the Authorize button on the top right corner of the documentation page above)

Last updated on