Using OData in Web API v3 - HxGN SDx - Update 70 - Administration & Configuration - Hexagon

The Web API v3 is a fully-featured and easy-to-integrate OData RESTful API. It provides the ability to interact, automate, and simplify complex repetitive tasks or multi-step actions, such as creating scripts, and uses the standard GET, POST, PATCH, PUT, and DELETE request methods.

The following sections detail Web API v3 examples of OData syntax, headers, and service calls that can be used to create an OData POST or GET request. These can easily be configured for your own system. The delivered standard API group used for these examples is SDXDEV.

To send a request to the SDx API, your URL must include specific components in a specific order. This documentation shortens URL paths by using <Access_URL> as a placeholder for some of the URL components. To learn more about URL components and the <Access_URL> placeholder, see Service Request URL Formation.

The Web API v3 provides:

• Consistency and compliance with Hexagon OData standards.

• Discoverable data definitions and vocabularies, including metadata generation.

• Exposed entities with full object properties, including structural and navigation properties.

• Create, Read, Update, and Delete operations on exposed entities.

  Web API v2 only allows these CRUD operations using the objects endpoint.

You can use the Web API v3 to:

• Expose Class Definition and Interface Definition types directly to the Web API v3 through the ISPFServices[ClassDef|InterfaceDef]Ext interface definition.

• Group Class Definition and Interface Definition types using the SPF objects APIGroup.

• Configure the entity single and set names using properties on the ISPFServices[ClassDef|InterfaceDef]Ext interface definition.

• Relate ComponentSchema instances to an APIGroup, which exposes all componentized Class Definitions.

• Access Entities and the relevant entity alias in the URL path use an APIGroup. For example:

  <ACCESS_URL>/api/v3/[APIGroup]/[ClassDef|InterfaceDefAlias

The delivered API group for HxGN SDx is SDXDEV.

The following shows an example of the schema changes needed to expose both a class definition (Pipe) and an interface definition (IPipeRun) to the API group (SDXDEV).

  <ClassDef>

    <IObject UID="Pipe" Name="Pipe" Description="Pipe" />

    <ISPFServicesClassDefExt SPFClassDefExposedName="Pipe"

                             SPFClassDefExposedSetName="Pipes" />

  </ClassDef>

  <Rel>

    <IObject UID="SDXDEV.APIGroupSchemaItem.Pipe" />

    <IRel UID1="SDXDEV" UID2="Pipe" DefUID="APIGroupSchemaItem" />

  </Rel>

  <InterfaceDef>

    <IObject UID="IPipeRun" Name="IPipeRun" Description="IPipeRun" />

    <ISPFServicesInterfaceDefExt SPFInterfaceDefExposedName="PipeRun"

                                 SPFInterfaceDefExposedSetName="PipeRuns" />

  </InterfaceDef>

  <Rel>

    <IObject UID="SDDEV.APIGroupSchemaItem.IPipeRun" />

    <IRel UID1="SDXDEV" UID2="IPipeRun" DefUID="APIGroupSchemaItem" />

  </Rel>

This will result in the following EntityType and EntitySet references being shown in the API metadata document for the API group. For example, <ACCESS_URL>/api/v3/SDXDEV/$metadata.

<EntityType Name="Pipes" BaseType="Intergraph.SPF.Server.API.Model.SPFObject"

OpenType="true">

...

</EntityType

<EntityType Name="PipeRun" BaseType="Intergraph.SPF.Server.API.Model.SPFObject"

OpenType="true">

...

</EntityType

<EntitySet Name="Pipes" EntityType="Intergraph.SPF.Server.API.Model.Pipe" />

<EntitySet Name="PipeRuns" EntityType="Intergraph.SPF.Server.API.Model.PipeRun" />

If a class or interface definition is related to an API group, and the name or set-name is not defined, the name of the class or interface definition is used as the entity-type name and pluralization is attempted on the entity-set name. For example, Pipe -> Pipes.