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. All examples use a short notation of the full URL. For example, . . /api/v3/ADW/DevelopmentTags.
When you create a URL using OData syntax, the URL is made up of segments to cover each parameter and provides the ability to interact, automate, and simplify complex repetitive tasks using the standard GET, POST, PATCH, PUT, and DELETE request methods.
When you use Web API v1, v2, or v3, the full OData URL for HxGN SDx is made up of the following segments:
Post https://<MachineName>/<SiteName>/api/v2/<APIGroupName>/<ExposedName>
The following descriptions apply to the segment parameters.
|
Parameter |
Description |
|
<MachineName> |
The name of the machine where the software is running and being hosted. Displayed as [host] in the examples. |
|
<SiteName> |
The name given to the site when it was created on the server. |
|
<APIGroupName> |
The name of an existing APIGroup or you can create a group for functionality according to the product or product area. For example, you can create an APIGroup with a name of TMA and relate the Tag, Model, Asset, class definitions or interface definitions to the TMA group. |
|
<ExposedName> |
The name of the object type you want to work with. For example, the exposed named values for SPFClassDefIsExposedName, SPFInterfaceDefIsExposedName, SPFRelDefIsExposed, or SPFEdgeDefIsExposed. |
All examples displayed use a short annotation version of the full URL. For example, . . /api/v2/TMA/DevelopmentTags.
Web API v3 is not supported in SmartPlant Foundation.
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 using the APIGroup and the relevant entity alias in the URL path. For example, . . /api/v3/[APIGroup]/[ClassDef|InterfaceDefAlias].
The following shows an example of the schema changes needed to expose both a class definition (Pipe) and an interface definition (IPipeRun) to a given API group (APIG SIO).
<ClassDef>
<IObject UID="Pipe" Name="Pipe" Description="Pipe" />
<ISPFServicesClassDefExt SPFClassDefExposedName="Pipe"
SPFClassDefExposedSetName="Pipes" />
</ClassDef>
<Rel>
<IObject UID="SIO.APIGroupSchemaItem.Pipe" />
<IRel UID1="APIG_SIO" UID2="Pipe" DefUID="APIGroupSchemaItem" />
</Rel>
<InterfaceDef>
<IObject UID="IPipeRun" Name="IPipeRun" Description="IPipeRun" />
<ISPFServicesInterfaceDefExt SPFInterfaceDefExposedName="PipeRun"
SPFInterfaceDefExposedSetName="PipeRuns" />
</InterfaceDef>
<Rel>
<IObject UID="SIO.APIGroupSchemaItem.IPipeRun" />
<IRel UID1="APIG_SIO" 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, . . /api/v3/SIO/$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.