The reference documentation pages is section of the OpenApi developer portal where you'll find information about all the available service groups, services and endpoints.
It answers questions like:
- What are the available service groups?
- What are the services and endpoints in a given service group?
- How to access an endpoint and what are its request parameters?
- What are the response types of an endpoint?
- What authorization is needed to access an endpoint?
- What are the response codes returned by an endpoint and what do they mean?
How do I access Reference Documentation?
The referenced documentation is available from the top level menu "Reference Docs" under the OpenAPI space of the developer portal.
Understanding elements of Reference Documentation
The home page of the reference documentation shows all the available service groups.
As shown in the image above, Charts, Client Management, Portfolio etc. are the service groups.
At the top of the page there is a search functionality which you can use to perform a site-wide search including service groups.
Detailed Service Group Information
Clicking on a service group shows a detailed view of the service group. For example, when clicking Portfolio we get a view like this:
At the top we find a short textual summary of the purpose of the service group. This is followed by the list of services.
Selecting a service - for example Accounts, it takes to the service page where we can see a list of endpoints belonging to the service.
Selecting an endpoint we're taken to a detailed page describing
- URI of the resource.
- What are the parameters of the request and what are their types? Also, the origin specifies if the parameter must be supplied on the route, as a query string parameter or as part of the request body. If a parameter is required, it is represented with red background.
- An example of the request, how the final request should look like.
- An example of response sample in JSON format.
Endpoint Access Level
The Endpoint Access Level section gives us information about visibility, authorization and required permissions for the endpoint.
If visibility is set to 'External' the endpoint can be called by 3rd party applications.
Required Permissions specifies which claims must be present in the access token in order to be able to call the endpoint.
In the bellow example the token must include the claim: Personal Read.
Detailed parameter type
If a parameter is a complex type, the type is shown as a link, and clicking on the link presents a modal window with the detailed view of the complex type.
For example - in the image above AccountType is a complex data type, clicking on it we're presented with the following modal window describing the data type in more detail:
HTTP Response Codes
To learn about possible response and error codes returned by the endpoint click on the "View response code" link under "Response Parameters" section.
You'll see a modal window like the one below:
Streaming response
For streaming endpoints, the streaming response information and sample streaming data in JSON format is also shown under Response Example.
Streaming response parameters
Response example
