Where do I find and explore Smart APIs? - Intergraph Smart API Manager - 2020 (4.0) - Help

Intergraph Smart API Manager Help

Language
English
Product
Intergraph Smart API Manager
Search by Category
Help
Smart API Manager Version
4.0

Typically, Smart APIs are registered and managed in Smart API Manager, an API and identity management system developed by Hexagon PPM. This document refers to Smart API Manager in all of its content and examples. However, it is possible to configure other third-party OAuth 2.0 and OpenID Connect providers to support Smart APIs.

Though Smart APIs may be deployed in the cloud, they are also deployable and accessible on any customer's network.

Typically, users in Smart API Manager play one of two roles, based on group membership:

  • Administrators - belong to the System Administrators group. They can add and configure Smart APIs and other related items, like Groups and Users.

  • Developers - belong to the Developers group. They can add and configure Smart Clients, applications requiring authorization to use Smart APIs. In addition, developers have read-only access to Smart APIs and other information required for client development.

Discoverability

Smart APIs, as OData v4 web APIs, offer standard endpoints for discoverability, returning important information about available API resources and how to consume them.

There are several endpoints you can browse to learn about Smart API resources and features:

  • service document (also known as <service root>) - entry point for the Smart API, lists available resources.

    SHARED Tip When you review a Smart API in Smart API Manager, the URL that displays in the grid (or specific API detail page) is the service document.

  • $metadata - located at <service root>/$metadata (main metadata document), describes the data model for the Smart API.

  • description document - located at <service root>/description. This document displays important information about a Smart API, such as token issuer (service that issues access tokens for the API), supported claims, etc. and is also used to register a Smart API with Smart API Manager.

A Smart API can provide additional information about its entity data model via OData Vocabularies and Annotations, which are part of the standard OData v4 protocol.

Vocabularies

OData Vocabularies contain terms that are applied to $metadata (and instance data) for Smart APIs. A vocabulary is simply an XML namespace containing terms. Each term defines information (for example, a characteristic or behavior) that further describes data.

From the service root, you will find additional $metadata documents containing vocabulary terms:

<service root>/Vocabularies/Core/$metadata - provides a vocabulary of terms to add more detailed information about data types (for example., provide a Description or DisplayName for an entity or property). This vocabulary contains a reference to the Core vocabulary published by OASIS.

<service root>/Vocabularies/Capabilities/$metadata - provides a vocabulary of terms that describe capabilities for a Smart API. This vocabulary contains a reference to the Capabilities vocabulary published by the OASIS consortium that maintains the OData protocol.

Capabilities annotations convey whether a Smart API is capable of a particular functionality, for example: CRUD operations for entity sets (can you insert, update, or delete instances of an entity), asynchronous requests (can you call an action or function asynchronously), behaviors for navigation properties (can you count or expand navigation properties), and so on.

<service root>/Vocabularies/Measures/$metadata - provides a vocabulary of terms to better describe data types related to measurement (for example, Scale or Unit). This vocabulary pulls in terms from the Measures vocabulary published by OASIS.

Annotations

Annotations are supported by vocabulary terms (an annotation is the application of a vocabulary term to data). For example, an annotation can extend information about an entity or property, providing more detail about how the resource behaves.

From the service root, you will find additional $metadata documents containing targeted annotations for a Smart API's data model:

<service root>/Annotations/$metadata - annotations related to the entity data model in general.

<service root>/Capabilities/$metadata - annotations related to the capabilities for a Smart API's entity data model.

Smart APIs also support the concept of Instance Annotations, wherein additional information for unique instances of an entity is provided (versus metadata annotations, which apply to all instances of a particular entity). The accompanying help or documentation for a specific Smart API resource outlines if instance annotations are supported and how to request the instance annotations.

Smart API resources often rely on metadata annotations, so it's important to understand how to find and interpret the annotations. Relevant metadata documents and specific annotations are referenced in each resource topic where applicable.

Smart API Explorer

Smart API Manager also provides a built-in API explorer, accessible from the details page for each Smart API. The Smart API Explorer is a web client that makes it easy for a software developer to browse available resources, discover functionality, and test calling API resources. Smart API Explorer provides a friendly alternative to reading metadata documents manually.

See Explore a Smart API for more information.