> For the complete documentation index, see [llms.txt](https://adiom.gitbook.io/data-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adiom.gitbook.io/data-api/getting-started/quickstart.md).

# Quickstart

The easiest way to try Data API is using our **free sandbox environment** at [dapi-sandbox.adiom.io](https://dapi-sandbox.adiom.io), where we host Data API-as-a-Service for MongoDB. See [Running Locally](/data-api/getting-started/quickstart/running-locally.md)for instructions on how to run Data API on your machine.

[Contact us](https://www.adiom.io/contact) or join our [Discord server](https://discord.gg/r4xzVfMQeU) if you want to see the source code or try a self-hosted version.

This guide assumes some familiarity with protobufs and gRPC. If you would like a refresher, we suggest  [this page](https://grpc.io/docs/what-is-grpc/introduction/).

{% hint style="info" %}
You can bootstrap your proto and config files from an existing MongoDB instance with the [mongoinfer tool](https://github.com/adiom-data/dapi-tools)
{% endhint %}

## 1. Create and compile a proto file

We start with defining endpoints and messages (or objects) that our service will operate with. You can use the following example and save it as **example.proto** in a new directory:

```
syntax = "proto3";

package example;

option go_package = "github.com/adiom-data/dapi/example";

service MyService {
    rpc Put(PutRequest) returns (PutResponse);
    rpc Get(GetRequest) returns (GetResponse);
}

message PutRequest {
    string name = 1;
}

message PutResponse {
    string _id = 1;
}

message GetRequest {
    string name = 1;
}

message GetResponse {
    string _id = 1;
    string name = 2;
}
```

Now we need to *compile* the proto file into **protos.pb**:

```bash
buf build -o protos.pb
```

{% hint style="info" %}
You may need to install [buf](https://github.com/bufbuild/buf) on your system
{% endhint %}

## 2. Create config file

We need to define the logic behind the endpoints. We will use a configuration file that you can save as **config.yaml**. DAPI supports various options that you can find on the [Concepts](/data-api/getting-started/concepts.md) page. We only use a subset of those here.

```yaml
interceptors:
  - name: Auth
    config:
      token: hello
  - name: MongoDB
    config:
      url: <ATLAS_CONN_STRING> # leave blank to use a DAPI-hosted MongoDB version
services:
  example.MyService:
    database: db
    collection: col
    unauthenticated: true
    endpoints:
      Get:
        findone:
          filter: '{ "name": req.name }'
      Put:
        auth: 'claims.role == "admin"'
        insertone:
          document: 'req'
```

{% hint style="info" %}
When authorization is enabled, the hosted DAPI version automatically creates three different roles and associated JWT tokens that you can use in the config file: "user", "agent", and "admin". It also adds the "email" claim with the registered user's email address so you can do something like:

```
auth: claims.role == "user" && claims.email == req.email
insertone:
          document: 'req'
```

{% endhint %}

## 3. Create and deploy the service

Create an account at [dapi-sandbox.adiom.io](https://dapi-sandbox.adiom.io), and deploy your service!

<figure><img src="https://4211308970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB2xwJ3fa5RUPg0ZyxPiH%2Fuploads%2FVwWdoKjo9BSVDkFf8gV8%2Fimage.png?alt=media&amp;token=74080b22-8778-4262-9607-2b134fc9cae1" alt=""><figcaption></figcaption></figure>

<figure><img src="https://4211308970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB2xwJ3fa5RUPg0ZyxPiH%2Fuploads%2FCloSI9OrIVnUYtV7PA4v%2Fimage.png?alt=media&amp;token=76b20bc1-ca3e-4dc1-a5d0-0eba5e740342" alt=""><figcaption></figcaption></figure>

<figure><img src="https://4211308970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB2xwJ3fa5RUPg0ZyxPiH%2Fuploads%2F8Ych9Ct1BJImFIPDJw37%2Fimage.png?alt=media&amp;token=4388c6da-9c15-4233-878f-a3d7d57371ac" alt=""><figcaption></figcaption></figure>

After the service is deployed, try the following commands:

```bash
# Create a new item using admin JWT token
grpcurl -H "dapi-key: <API_KEY>" -H "authorization: Bearer <JWT_TOKEN_ADMIN>" -d '{"name":"Alex"}' 34.9.35.97:80 example.MyService/Put

# Get the item that we just inserted (no need for authorization for that)
grpcurl -H "dapi-key: <API_KEY> -d '{ "name": "Alex" }' 34.9.35.97:80 example.MyService/Get
```

{% hint style="info" %}
You may need to install [grpcurl](https://github.com/fullstorydev/grpcurl?tab=readme-ov-file#installation) on your system
{% endhint %}