Compose your API surface with Data API builder custom paths

In May, Data API builder (DAB) 2.0 was released to preview, and in June it went generally available. With this new release, DAB introduced a new feature for REST endpoints: the ability to customize endpoints with compound paths. This feature allows developers to compose a sophisticated API surface dedicated to their business structure, not their database topology. Let’s take a look.

Generating REST endpoints

With Data API builder (DAB), developers can safely expose their production SQL database as a REST, GraphQL, and MCP endpoint. In this article, we focus on REST. These endpoints are dynamically generated by the DAB engine with rich capabilities like native pagination, filtering, projection, caching, and throttling. These are the same types of features you would add to your custom endpoints, but without the engineering cost or time.

Exposing REST endpoints

A REST endpoint path is constructed from three parts. The first is the host name where Data API builder is hosted. For example, this could be localhost in the inner developer loop or an Azure domain when hosted in Azure Container Apps. The second part is the global runtime setting runtime.rest.path, which defaults to /api, a typical starting segment for most API endpoints.

The third part of the REST path is our new feature, compound paths. It is individually configured for every entity. For example, if you have a Customer entity exposed, your default path might coalesce to localhost/api/Customer, which works great for many deployments and has worked great for years.

However, entity path values like /external/Customer were not supported until release 2.0. With this new flexibility, different entities can be grouped by some business mnemonic to help clarify usage and enable better intuition around endpoint usage. Supporting as many subsegments as you need, Data API builder lets you compose your API surface in whatever direction best serves your business.

Entity configuration examples

Every entity provides its final REST endpoint path. This is the segment that now supports compound paths, letting you build out a tailored, intuitive API surface. In the examples below, we’ll show some scenarios with our example Customer entity.

Scenario 1: a simple endpoint

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    }
  },
  "entities": {
    "Customer": {
      "source": {
        "object": "dbo.Customer",
        "type": "table"
      },
      "rest": {
        "enabled": true,
        "path": "/Customer"
      }
    }
  }
}

The resulting REST path is https://localhost/api/Customer.

Or if you had several entities, you could see this:

https://localhost/api/Customer
https://localhost/api/Order
https://localhost/api/Invoice
https://localhost/api/CustomerAddress
https://localhost/api/Payment

Scenario 2: show the business in the path

You can use compound paths to organize endpoints by business area. This can make the API easier to understand, especially when many entities are exposed.

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    }
  },
  "entities": {
    "Customer": {
      "source": {
        "object": "dbo.Customer",
        "type": "table"
      },
      "rest": {
        "enabled": true,
        "path": "/sales/Customer"
      }
    }
  }
}

The resulting REST path is https://localhost/api/sales/Customer.

Or if you had several entities, you could see this:

https://localhost/api/sales/Customer
https://localhost/api/sales/Order
https://localhost/api/sales/Invoice
https://localhost/api/accounting/Payment
https://localhost/api/support/CustomerCase

Scenario 3: show the schema in the path

You can also use compound paths to reflect database schema or ownership. This can be useful when the API surface needs to preserve a familiar structure for developers.

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    }
  },
  "entities": {
    "Customer": {
      "source": {
        "object": "sales.Customer",
        "type": "table"
      },
      "rest": {
        "enabled": true,
        "path": "/sales/Customer"
      }
    }
  }
}

The resulting REST path is https://localhost/api/sales/Customer.

Or if you had several entities, you could see this:

https://localhost/api/dbo/Customer
https://localhost/api/sales/Order
https://localhost/api/sales/Invoice
https://localhost/api/billing/Payment
https://localhost/api/support/CustomerCase

Conclusion

Compound REST paths make it easier to shape a Data API builder API around your application and business needs. You can keep simple paths when they are enough, or add structure when it helps developers understand and use the API. Data API builder still handles the endpoint generation, security, and query behavior for you.

Best of luck!