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

Field	Type	Description
`entity`	Map	Marks an object type as an entity.
`entity.key`	String	An array that must not be empty. Each item must reference a field that is a key of the entity.

entity

Map

Marks an object type as an entity.

entity.key

String

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

Field	Type	Description
`entity-reference`	An array of objects	A list of all the references.
`entity-reference.[n].name`	String	The name of the type being referenced. May or may not be part of the API.
`entity-reference.[n].fieldName`	String	The name of the new field that will be created for this type.
`entity-reference.[n].keyMapping`	Map	The keys of the map represent the fields of this type, and the values represents the keys of the referenced type.

entity-reference

An array of objects

A list of all the references.

entity-reference.[n].name

String

The name of the type being referenced. May or may not be part of the API.

entity-reference.[n].fieldName

String

The name of the new field that will be created for this type.

entity-reference.[n].keyMapping

Map

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

Field	Type	Description
`entity-provider`	Map	Marks that this endpoint returns entity instances.
`entity-reference.keyMapping`	Map	The keys of the map represent parameters of this operation, and the values represents the keys of the target type.

entity-provider

Map

Marks that this endpoint returns entity instances.

entity-reference.keyMapping

Map

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

Field	Type	Description
`http-method-override`	Map	Marks an operation to be overridden.
`http-method-override.method`	String	The HTTP method that will be used to override the original operation.

http-method-override

Map

Marks an operation to be overridden.

http-method-override.method

String

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

Field	Type	Description
`datagraph`	Map	A container for DataGraph-specific annotations.
`datagraph.hide`	Boolean	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.

datagraph

Map

A container for DataGraph-specific annotations.

datagraph.hide

Boolean

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

Field	Type	Description
`datagraph`	Map	A container for DataGraph-specific annotations.
`datagraph.name`	String	The desired name for the element in DataGraph. If possible, use a pattern for valid names.

datagraph

Map

A container for DataGraph-specific annotations.

datagraph.name

String

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

Anypoint DataGraph API Extension Reference

Object Type Extensions

Structure

OAS Example

RAML Example

Entity References

Structure

OAS Example

RAML Example

Entity Provider

Structure

OAS Example

RAML Example

HTTP Method Override

Structure

OAS Example

RAML Example

DataGraph-specific Extensions

Hide

Structure

OAS Example

RAML Example

Name

Structure

OAS Example

RAML Example

See Also