---
schema_version: "1"
id: 6114a9763d5543537ae32d73d67d2ab81ff87f198ed828d79387422fb2045b35
title: Anypoint DataGraph API Extension Reference
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/datagraph/api-extensions.md
canonical_url: https://docs.mulesoft.com/datagraph/api-extensions
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 011b886d16d5ccb81a7537a38573361ceef34be73cbd31a2f676874210e75ba1
description: MuleSoft Documentation Site
latest: true
---
---
product: DataGraph
---

# Anypoint DataGraph API Extension Reference

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This guide defines API extensions for DataGraph.

## Object Type Extensions

This extension marks that an object type has a primary key, and thus can be used as a reference or
extension.

This extension applies to `ObjectType`.

### Structure

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>entity</code></p></td><td><p>Map</p></td><td><p>Marks an object type as an entity.</p></td></tr><tr><td><p><code>entity.key</code></p></td><td><p>String</p></td><td><p>An array that must not be empty. Each item must reference a field that is a key of the entity.</p></td></tr></tbody></table>

### OAS Example

```copy
components:
  schemas:
    Customer:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  email:
          type: string
    	  id:
          type: string
    	  ...
```

### RAML Example

```copy
types:
  Customer:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	email:
        type: string
    	id:
        type: string
    	...
```

## Entity References

This extension generates a DataGraph _link_ from the properties of one type to another type. The
link can be to a type that is not defined in the same API spec.

This extension applies to `ObjectType`.

### Structure

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>entity-reference</code></p></td><td><p>An array of objects</p></td><td><p>A list of all the references.</p></td></tr><tr><td><p><code>entity-reference.[n].name</code></p></td><td><p>String</p></td><td><p>The name of the type being referenced. May or may not be part of the API.</p></td></tr><tr><td><p><code>entity-reference.[n].fieldName</code></p></td><td><p>String</p></td><td><p>The name of the new field that will be created for this type.</p></td></tr><tr><td><p><code>entity-reference.[n].keyMapping</code></p></td><td><p>Map</p></td><td><p>The keys of the map represent the fields of this type, and the values represents the keys of the referenced type.</p></td></tr></tbody></table>

### OAS Example

```copy
components:
  Schemas:
    Order:
    	x-entity-reference:
        - name: Customer
          fieldName: customer
          keyMapping:
            customerId: id
        - name: Store
          fieldName: store
          keyMapping:
            storeId: id
      properties:
    	  orderItems:
          ...
    	  customerId:
          type: string
    	  storeId:
          type: string
    Customer:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  email:
          type: string
    	  id:
          type: string
    Store:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  id:
          type: string
    	  ...
```

### RAML Example

```copy
types:
  Order:
    (dg.entity-reference):
      - name: Customer
        fieldName: customer
        keyMapping:
          customerId: id
      - name: Store
        fieldName: store
        keyMapping:
          storeId: id
    properties:
    	orderItems:
        ...
    	customerId:
        type: string
    	storeId:
        type: string
  Customer:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	email:
        type: string
    	id:
        type: string
    	...
  Store:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	id:
        type: string
```

## Entity Provider

This extension marks that an endpoint returns instances of an entity by id. In DataGraph, this is
the _default query method_.

This extension applies to GET operations.

### Structure

The target is not specified because it is implicit in the operation.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>entity-provider</code></p></td><td><p>Map</p></td><td><p>Marks that this endpoint returns entity instances.</p></td></tr><tr><td><p><code>entity-reference.keyMapping</code></p></td><td><p>Map</p></td><td><p>The keys of the map represent parameters of this operation, and the values represents the keys of the target type.</p></td></tr></tbody></table>

### OAS Example

```copy
Schemas:
    Customer:
  	x-entity:
    	  key: [id]
  	properties:
    	  name:
          type: string
    	  email:
          type: string
    	  1:
          type: string
    	  ...
paths:
  "/customers/{customerId}":
    get:
  	x-entityProvider:
    	  keyMapping:
          customerId: id
  	parameters:
    	  - in: query
          name: summaryView
          default: true
          schema:
          type: boolean
  	...
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
            	$ref: "#/components/schemas/Customer"
```

### RAML Example

```copy
types:
  Customer:
    (dg.entity):
      key: [id]
    properties:
    	name:
        type: string
    	email:
        type: string
    	id:
        type: string
    	…

/customer/{customerId}:
  uriParameters:
    customerId: string
  get:
    (dg.entityProvider):
      keyMapping:
        customerId: id
    responses:
      200:
        application/json:
          body: Customer
```

## HTTP Method Override

Use this extension to treat a POST method as a GET method. This extension converts the POST method
into a query operation instead of a mutation.

This extension applies to operations.

### Structure

The target is not specified because it is implicit in the operation.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>http-method-override</code></p></td><td><p>Map</p></td><td><p>Marks an operation to be overridden.</p></td></tr><tr><td><p><code>http-method-override.method</code></p></td><td><p>String</p></td><td><p>The HTTP method that will be used to override the original operation.</p></td></tr></tbody></table>

### OAS Example

```copy
paths:
  "/customers":
    post:
  	x-http-method-override:
          method: get
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
                type: array
                items:
                  $ref: "#/components/schemas/Customer"
```

### RAML Example

```copy
/customers:
  post:
    (dg.http-method-override):
      method: get
    responses:
      200:
        body:
          application/json:
            type: Customer[]
```

## DataGraph-specific Extensions

The main annotation `datagraph` cannot have the same name for different domains. Because of this,
the annotations for operations, type, and object properties use postfixes:

- Operations: -method

- Type: -type

- Object properties: -field

### Hide

Use this extension to mark an element as hidden. Hidden elements aren’t shown in the unified schema,
and DataGraph doesn’t return them in any queries.

This extension applies to:

- Operations

- Any type

- Object properties

### Structure

The target is not specified because it is implicit in the operation.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>datagraph</code></p></td><td><p>Map</p></td><td><p>A container for DataGraph-specific annotations.</p></td></tr><tr><td><p><code>datagraph.hide</code></p></td><td><p>Boolean</p></td><td><p>If <code>true</code>, the element is hidden in the unified schema. If <code>false</code>, the element is not hidden, which provides the same result as not setting the annotation.</p></td></tr></tbody></table>

### OAS Example

```copy
components:
  Schemas:
    Customer:
  	x-datagraph:
    	  hide: true
  	properties:
    	  name:
          type: string
    	  email:
          type: string
  	    x-datagraph:
    	      hide: true
    	  id:
          type: string
    	  ...
paths:
  "/customers/{customerId}":
    get:
  	x-datagraph:
    	  hide: true
  	parameters:
    	  - in: query
          name: summaryView
          default: true
          schema:
          type: boolean
  	...
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
            	$ref: "#/components/schemas/Customer"
```

### RAML Example

```copy
types:
  Customer:
    (dg.datagraph):
      hide: true
    properties:
    	name:
        type: string
    	email:
        type: string
        (dg.datagraph):
          hide: true
    	id:
        type: string
    	…

/customer/{customerId}:
  uriParameters:
    customerId: string
  get:
    (dg.datagraph):
      hide: true
    responses:
      200:
        application/json:
          body: Customer
```

## Name

Use this extension to set the desired name of an element in DataGraph, such as defining specific
names for elements in the unified schema. You can also use this extension to federate types from
different APIs without changing the underlying APIs.

This extension applies to:

- Operations

- Any type

- Object properties

### Structure

The target is not specified because it is implicit in the operation.

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><p><code>datagraph</code></p></td><td><p>Map</p></td><td><p>A container for DataGraph-specific annotations.</p></td></tr><tr><td><p><code>datagraph.name</code></p></td><td><p>String</p></td><td><p>The desired name for the element in DataGraph. If possible, use a pattern for valid names.</p></td></tr></tbody></table>

### OAS Example

```copy
components:
  Schemas:
    Customer:
  	x-datagraph:
    	  name: SalesCustomer
  	properties:
    	  name:
          type: string
    	  e-mail:
          type: string
  	    x-datagraph:
    	      name: email
    	  id:
          type: string
    	  ...
paths:
  "/customers/{customerId}":
    get:
  	x-datagraph:
    	  name: getCustomer
  	parameters:
    	  - in: query
          name: summaryView
          default: true
          schema:
          type: boolean
  	...
  	responses:
    	'200':
         content:
            application/json:
          	  schema:
            	$ref: "#/components/schemas/Customer"
```

### RAML Example

```copy
types:
  Customer:
    (dg.datagraph):
      name: SalesCustomer
    properties:
    	name:
        type: string
    	e-mail:
        type: string
          (dg.datagraph):
            name: email
    	id:
        type: string
    	…

/customer/{customerId}:
  uriParameters:
    customerId: string
  get:
    (dg.datagraph):
      name: getCustomer
    responses:
      200:
        application/json:
          body: Customer
```

## See Also

- [Using Anypoint Platform DataGraph CLI and API Extensions](https://docs.mulesoft.com/datagraph/overview-cli-extensions)

- [Anypoint CLI DataGraph Command Reference](https://docs.mulesoft.com/datagraph/datagraph-cli)