Trading Partner Management Object Model: REST Endpoint
Important
Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.
If you're brand new to Logic Apps, then we suggest getting started here:
-
Create your first logic app, or quickly get started using a pre-built template
-
View all the available connectors you can use in your logic apps
REST endpoint used for the TPM OM APIs.
After you have provisioned your BizTalk Service (steps at https://go.microsoft.com/fwlink/p/?LinkId=299821), a deployment URL is created for your environment. You can use that URL to arrive at the REST endpoint used for the TPM OM APIs.
In this topic:
Discovering the TPM OM Entities
TPM OM API: What to do Where?
Connecting to the TPM OM API REST Endpoint
Creating .NET Applications Using the TPM OM API
Discovering the TPM OM Entities
TPM OM API uses the $metadata operation to make the entities discoverable. The URI to retrieve the metadata is:
<base_URL>/default/$PartnerManagement/$metadata
Here, <base_URL> refers to the deployment URL of the BizTalk Services environment. For example, if the deployment URL is https://mybiztalkservice.biztalk.windows.net, the URL to retrieve the metadata should be https://mybiztalkservice.biztalk.windows.net/default/$PartnerManagement/$metadata.
This URL allows you to retrieve all valid entity types, entity properties, associations, and so on. You can also view the metadata by hitting the endpoint in a browser.
TPM OM API: What to do Where?
The TPM OM API enables users to write applications to create and manage the entities required in business-to-business messaging. While the object model aims to have complete parity with the operations available through the portal, there are some tasks that are done outside the use of the object model. This section provides information on the tasks that can be performed using the object model, the tasks that can be performed using the PowerShell CmdLets to manage the BizTalk Service, and the tasks that can be performed using the BizTalk Services Portal.
Using the Object Model |
Using the PowerShell Cmdlets |
Using the Portal |
|
|---|---|---|---|
Create Partner |
√ |
√ |
|
--- Create Profile |
√ |
√ |
|
--- Add Identities |
√ |
√ |
|
--- Upload Certificate |
√ |
√ |
|
Create X12 Agreement |
√ |
√ |
|
--- Set Partner1, Partner2 |
√ |
√ |
|
--- Add Identities |
√ |
√ |
|
--- Upload Schema |
√ |
√ |
|
--- Create Batch |
√ |
√ |
|
Deploy X12 bridges |
√ |
||
--- Add Route Settings |
√ |
||
--- Upload Transform |
√ |
√ |
|
Create AS2 Agreement |
√ |
√ |
|
--- Set Partner1, Partner2 |
√ |
√ |
|
Deploy AS2 bridges |
√ |
||
--- Add Route Settings |
√ |
||
Create EDIFACT Agreement |
√ |
√ |
|
--- Set Partner1, Partner2 |
√ |
√ |
|
--- Add Identities |
√ |
√ |
|
--- Upload Schema |
√ |
√ |
|
--- Create Batch |
√ |
√ |
|
Deploy EDIFACT bridges |
√ |
||
--- Add Route Settings |
√ |
||
--- Upload Transform |
√ |
√ |
Connecting to the TPM OM API REST Endpoint
To retrieve the metadata about TPM OM entities, you can simply hit the endpoint in a browser. However, if you want to perform any CRUD operations on the entities, you must request messages that include the required header values as well as message payload (if required).
You must include the required headers for invoking the REST endpoint.
TPM OM API enables users to send OData-based HTTP requests to create TPM OM entities and receive responses in verbose JSON, atom+pub, or straight XML. Because the TPM OM API conforms to Azure design guidelines, there is a set of required HTTP headers that each client must use when connecting to the TPM OM API REST endpoint, as well as a set of optional headers that can be used. The following sections describe the headers and HTTP verbs you can use with the TPM OM API.
For a list of required and optional headers, see the HTTP Request, HTTP Response, and HTTP Verbs sections (in this topic).
Wherever applicable, you must include the required property names with appropriate values. For a list of entities and their properties, see TPM OM API: Exposed Entities and Properties.
Supported HTTP Request Headers
Every call made to the TPM OM API REST endpoints must include a set of required headers and also a set of optional headers, if you want to. The following table lists the required headers:
Required Headers
Header |
Type |
Value |
|---|---|---|
Authorization |
WRAP Access Control tokens |
The value must include the access token provided by the Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS). To retrieve an Access Control token using the WRAP protocol, see https://msdn.microsoft.com/library/windowsazure/hh674475.aspx. |
Host |
String |
Specifies the host and the port number of the resource being targeted. |
DataServiceVersion |
Decimal |
1.0 |
MaxDataServiceVersion |
Decimal |
3.0 |
x-ms-version |
Decimal |
1.0 |
If-Match |
Entity tag |
Specifies that an operation is performed only if the entity tag specified in the request header matches with the entity tag of the object. Note This header is required only when performing update or delete operations. |
Note
Because the TPM OM API uses OData to expose its underlying asset metadata repository through REST APIs, the DataServiceVersion and MaxDataServiceVersion headers should be included in any request. If they are not included, then currently the TPM OM API assumes the DataServiceVersion value in use is 1.0.
Optional Headers
Header |
Type |
Value |
|---|---|---|
Date |
RFC 1123 date |
Timestamp of the request |
Accept |
Content type |
The requested content type for the response such as the following:
|
Accept-Encoding |
Gzip, deflate |
GZIP and DEFLATE encoding, when applicable. |
Accept-Language |
"en", "es", and so on |
Specifies the preferred language of the response. |
Accept-Charset |
Charset type like UTF-8 |
Default is UTF-8 |
X-HTTP-Method |
HTTP Method |
Allows clients or firewalls that do not support HTTP methods like PUT or DELETE to use these methods, tunneled via a GET call. |
Content-Type |
Content type |
Content type of the request body in POST and PUT requests. |
Supported HTTP Response Headers
The following is a set of headers that may be returned to you depending on the resource you were requesting and the action you intended to perform.
Header |
Type |
Value |
|---|---|---|
Date |
RFC 1123 date |
The date that the request was processed |
Content-Type |
Varies |
The content type of the response body |
Content-Encoding |
Varies |
Gzip or deflate, as appropriate |
Cache-Control |
- |
Specifies whether caching mechanisms, from server to client, may cache the object. |
Content-Length |
Content type |
The length of the response body |
Server |
- |
A server name. |
X-Content-Type-Options |
Content type |
The only possible value “nonsniff” prevents browsers from MIME-sniffing a response from the declared content-type. |
Supported HTTP Verbs
The following is a complete list of HTTP verbs that are supported by the TPM OM API and can be used when making HTTP requests:
VERB |
Description |
|---|---|
GET |
Returns the current value for an entity |
POST |
Creates an object (or submits a command) based on the provided data |
PUT |
Replaces an object, or creates a new object (when applicable) |
DELETE |
Deletes an object |
MERGE |
Updates an existing object with named property changes. |
Creating .NET Applications Using the TPM OM API
Because the TPM OM API is based on the OData protocol, you can use the WCF Data Services to build .NET applications that perform CRUD operations on the entities. For more information on how create .NET applications using the TPM OM API, see Creating .NET Applications Using TPM OM REST API.
See Also
Trading Partner Management Object Model (TPM OM): API Reference