Skip to main content

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":"your@email.com"
      },
      "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.

Last updated on