Anypoint DataGraph API Extension Reference | MuleSoft Documentation
# Anypoint DataGraph API Extension Reference
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
Field | Type | Description  
---|---|---  
Marks an object type as an entity.  
`entity.key` | An array that must not be empty. Each item must reference a field that is a key of the entity.  
### OAS Example
```
components:
 schemas:
  Customer:
 	x-entity:
  	 key: [id]
 	properties:
  	 name:
     type: string
  	 email:
     type: string
  	 id:
     type: string
  	 ...
```

### RAML Example
```
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
Field | Type | Description  
---|---|---  
`entity-reference` | An array of objects | A list of all the references.  
`entity-reference.[n].name` | The name of the type being referenced. May or may not be part of the API.  
`entity-reference.[n].fieldName` | The name of the new field that will be created for this type.  
`entity-reference.[n].keyMapping` | The keys of the map represent the fields of this type, and the values represents the keys of the referenced type.  
### OAS Example
```
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
```
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.
Field | Type | Description  
---|---|---  
`entity-provider` | Marks that this endpoint returns entity instances.  
`entity-reference.keyMapping` | The keys of the map represent parameters of this operation, and the values represents the keys of the target type.  
### OAS Example
```
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
```
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.
Field | Type | Description  
---|---|---  
`http-method-override` | Marks an operation to be overridden.  
`http-method-override.method` | The HTTP method that will be used to override the original operation.  
### OAS Example
```
paths:
 "/customers":
  post:
 	x-http-method-override:
     method: get
 	responses:
  	'200':
     content:
      application/json:
     	 schema:
        type: array
        items:
         $ref: "#/components/schemas/Customer"
```

### RAML Example
```
/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.
Field | Type | Description  
---|---|---  
`datagraph` | A container for DataGraph-specific annotations.  
`datagraph.hide` | If `true`, the element is hidden in the unified schema. If `false`, the element is not hidden, which provides the same result as not setting the annotation.  
### OAS Example
```
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
```
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.
Field | Type | Description  
---|---|---  
`datagraph` | A container for DataGraph-specific annotations.  
`datagraph.name` | The desired name for the element in DataGraph. If possible, use a pattern for valid names.  
### OAS Example
```
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"
```
## 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.
Field | Type | Description  
---|---|---  
`datagraph` | A container for DataGraph-specific annotations.  
`datagraph.name` | The desired name for the element in DataGraph. If possible, use a pattern for valid names.  
### OAS Example
```
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
```
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
  * Anypoint CLI DataGraph Command Reference