Programming Using the REST API

You can use any programming or scripting language to access the REST API, as long as it can send HTTP requests and receive responses.

Service Base Address

http://<server>:5181/odata

The base address identifies the root of the REST API service. It includes:

  • The protocol (HTTP/HTTPS)
  • The machine name hosting the service
  • The port number (default: 5181, may differ depending on configuration)

The exact address is shown in the Power Server Management Console.

NoteNote

The REST API service is disabled by default and must be enabled before use.

Service Metadata Document

Each OData service exposes a metadata document.

ImportantAlways retrieve the metadata document from your server

The service and metadata documents in this manual are illustrative examples. They are shortened, and they do not necessarily match the current version of the REST API or what is enabled on a particular server. Entity sets, properties, custom fields, annotations and code types differ between versions and installations: for example, only activated custom fields appear.

Always retrieve $metadata from the server you integrate with, and build your client on that document, not on the examples in this manual.

JSON Metadata Example

Send an HTTP GET request to the base address:

GET http://myserver:5181/odata

Response (example):

HTTP/1.1 200 OK
Content-Length: 704
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"http://myserver:5181/odata/$metadata","value":[
  {"name":"ServiceRequests","kind":"EntitySet","url":"ServiceRequests"},
  {"name":"Problems","kind":"EntitySet","url":"Problems"},
  {"name":"Changes","kind":"EntitySet","url":"Changes"},
  {"name":"Incidents","kind":"EntitySet","url":"Incidents"},
  {"name":"ConfigurationItems","kind":"EntitySet","url":"ConfigurationItems"},
  {"name":"Workorders","kind":"EntitySet","url":"Workorders"},
  {"name":"EmailServiceRequests","kind":"EntitySet","url":"EmailServiceRequests"},
  {"name":"Services","kind":"EntitySet","url":"Services"},
  {"name":"MaintenanceContracts","kind":"EntitySet","url":"MaintenanceContracts"},
  {"name":"Projects","kind":"EntitySet","url":"Projects"},
  {"name":"ServiceLevelAgreements","kind":"EntitySet","url":"ServiceLevelAgreements"},
  {"name":"Workgroups","kind":"EntitySet","url":"Workgroups"},
  {"name":"Persons","kind":"EntitySet","url":"Persons"},
  {"name":"Locations","kind":"EntitySet","url":"Locations"},
  {"name":"Organizations","kind":"EntitySet","url":"Organizations"},
  {"name":"ServiceLevels","kind":"EntitySet","url":"ServiceLevels"},
  {"name":"Templates","kind":"EntitySet","url":"Templates"}]
}

XML Metadata Example

Append $metadata to the base address:

GET http://myserver:5181/odata/$metadata

Response (example):

HTTP/1.1 200 OK
Content-Length: 1548
Content-Type: application/xml
OData-Version: 4.0


<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
  <edmx:DataServices>
    <Schema Namespace="PROLIN.Web.OData.Model" xmlns="http://docs.oasis-open.org/odata/ns/edm">
      <EntityType Name="ServiceRequest">
        <Key>
          <PropertyRef Name="Uid" />
        </Key>
        <Property Name="Status" Type="PROLIN.Web.OData.Model.Code" />
        <Property Name="ClosureCode" Type="PROLIN.Web.OData.Model.Code" />
        <Property Name="Medium" Type="PROLIN.Web.OData.Model.Code" />
        <Property Name="Priority" Type="PROLIN.Web.OData.Model.Code" />
        <Property Name="Solution" Type="Edm.String" />
        <Property Name="Deadline" Type="Edm.DateTimeOffset" />
        <Property Name="Description" Type="Edm.String" />
        <Property Name="ID" Type="Edm.Int64" />
        <Property Name="Information" Type="Edm.String" />
        <Property Name="SourceID" Type="Edm.String" />
        <Property Name="Uid" Type="Edm.Int64" Nullable="false" />
        <NavigationProperty Name="Caller" Type="PROLIN.Web.OData.Model.Person" />
        <NavigationProperty 
          Name="Attachments"
          Type="Collection(PROLIN.Web.OData.Model.AttachedItem)"
          ContainsTarget="true" />
        <NavigationProperty 
          Name="HistoryLines"
          Type="Collection(PROLIN.Web.OData.Model.ServiceRequestHistoryLine)"
          ContainsTarget="true" />
      </EntityType>
      <ComplexType Name="Code">
        <Property Name="Text" Type="Edm.String" />
        <Property Name="Value" Type="Edm.Int64" />
      </ComplexType>
      <EntityContainer Name="PROLIN.SmartSuite">
        <EntitySet Name="ServiceRequests" EntityType="PROLIN.Web.OData.Model.ServiceRequest">
          <NavigationPropertyBinding Target="Persons" Path="Caller" />
        </EntitySet>  
      </EntityContainer>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

Data Response Types

  • By default, data is returned as JSON (lightweight and human-readable).
    More info: http://json.org

  • Starting with version 2.0, an access token is required for any read or write operation involving supported entities.
    See Token-based Authentication for more details.

  • Clients can request XML instead of JSON by specifying an Accept header:

Accept: application/xml

Or:

Accept: text/xml
Back to top