Forum Discussion

iliassoto_lgt's avatar
iliassoto_lgt
Frequent Visitor
5 months ago
Solved

REST API has two endpoints for creating items. Which one should I use?

In order to create items (such as a warehouse) the REST API exposes two endpoints:

POST https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/items (specifying the itemType in the body)

and 

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses

 

which one should we use? They have small differences regarding body. For example, the former uses defaultCollation while the latter uses collationType in order to express the desired collation. Is there a logic on why there are two endpoints? And which one will be prioritized in terms of development?

 

Sources:

Data Warehouse collation - Microsoft Fabric | Microsoft Learn

Items - Create Warehouse - REST API (Warehouse) | Microsoft Learn

 

 

 

CICD
  • Cookistador's avatar
    Cookistador
    5 months ago

    Hi iliassoto_lgt 

    With this kind of question, you get the classic consultant answer: it depends. 😁

     

    For a one-shot script or a small project → use the workload-specific endpoint (/warehouses, /lakehouses, etc.)
    Why?

    It exposes the complete parameter surface for that item type (collation, SKU hints, etc.)
    It tends to have better documented error responses for type-specific failures
    It's the endpoint the workload team actually owns and tests against — so it's the most reliable


    For generic tooling → use the generic Items endpoint (/items with itemType in the body)
    Why? Because if you're building something that handles multiple item types uniformly — a deployment pipeline that creates N different items from a config file, or any automation where you want a single consistent call pattern; the generic endpoint is cleaner to work with. One function, one schema, swap the itemType and you're done.

2 Replies

  • Cookistador's avatar
    Cookistador
    Icon for Super User rankSuper User
    5 months ago

    Hi iliassoto_lgt 

    With this kind of question, you get the classic consultant answer: it depends. 😁

     

    For a one-shot script or a small project → use the workload-specific endpoint (/warehouses, /lakehouses, etc.)
    Why?

    It exposes the complete parameter surface for that item type (collation, SKU hints, etc.)
    It tends to have better documented error responses for type-specific failures
    It's the endpoint the workload team actually owns and tests against — so it's the most reliable


    For generic tooling → use the generic Items endpoint (/items with itemType in the body)
    Why? Because if you're building something that handles multiple item types uniformly — a deployment pipeline that creates N different items from a config file, or any automation where you want a single consistent call pattern; the generic endpoint is cleaner to work with. One function, one schema, swap the itemType and you're done.