The content section provides the following information:
-
Overview: An introduction to the API Reference.
-
OData Concepts: Explains concepts that are necessary to effectively use our OData API. These include authorization, paging, expanding and selecting.
-
Responses: A table of response codes (200, 201, etc.) with their related methods (GET, POST, PATCH, PUT, DELETE) and descriptions.
-
Metadata: A file that is primarily used to provide information to client applications on the API entities, their properties, their navigations, and on the available service operations. This is provided primarily to aid in the import of data to the client applications. As an XML file, it is human-readable, so you can refer to the $metadata
file for much of the information about the API. For information on reading the $metadata
file, please see Understanding OData metadata.
-
Entity groupings: These match the top-level titles shown in the navigation sidebar. These are entity groupings in that they frequently cover the API endpoints for more than one entity. For example, the Group
entity set covers endpoints that relate to the Group
, GroupTemplates
, SystemGroupTemplates
, GroupMemberships
, GroupExternalObjects
, GroupGadgets
, and GroupGadgetObjects
entities. Each of these sections contains:
- a quick description of the entity grouping
- the request / response schema for the entity grouping
- descriptions of each of the entities within the entity grouping
- navigations for the entity grouping (when applicable)
- service operations for the entity grouping (when applicable)
-
Following the documentation on each entity grouping section is documentation on each endpoint of the entity grouping. That information varies depending on whether it is a POST, GET, PATCH, or DELETE operation. All endpoint documentation includes:
- The signature of the endpoint, which is the HTTP verb plus the endpoint’s resource path; for example: [GET] /Groups.
- A short description of the purpose or function of the API call.
- A Show Options drop-down menu that contains the Request Headers and Query Parameters required to make the API call:
- Request Headers (required):
Authorizaton
- Authentication credentials for HTTP authentication.
Accept
- Desired MIME type of the response (XML, JSON).
- Query Parameters (when applicable) - Descriptions and text boxes for inputting the various Query Parameters (paging, expanding, selecting) that are either required or are available for optional use with the API call.
- A Try button that will show the results of the API call when clicked, as long as the OAuth2 Token and the required Query Parameters are all set.