Skip to Content
Previous

Use the SAP Jam Collaboration OData API Reference

By Marc Bell

Try out each SAP Jam Collaboration endpoint and view the results using the OData API Reference.

Details

You will learn

In this tutorial, you will learn how to use the SAP Jam Collaboration OData API Reference, which provides full documentation for each endpoint, or API call. It also provides an excellent Try feature that allows users to try out each endpoint and view the results.


Step 1: Understand the main sections of the reference

The SAP Jam Collaboration OData API Reference is organized into the three sections shown in the following diagram.

API Reference sections
  • The banner section contains the title of the API reference and the OAuth2 token entry field, which allows you to enter the OAuth 2.0 Token generated in SAP Jam Collaboration.

  • The navigation sidebar shows a menu of the Introduction section, and all of the entity sections and their endpoints. Click an entity section title to expand that section and show its information in the content section. Click an endpoint signature to show its documentation.

  • The content section displays the documentation on each entity grouping (request / response schema, entities, endpoints, navigations and service operations).

Please log in to access this content.
Step 2: Dig deeper into the content section

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.
Please log in to access this content.
Step 3: Use the Try feature

Probably the greatest feature of our SAP Jam Collaboration OData API Reference is the Try feature, which allows you to try out an API call and see the result immediately. To use this feature, do the following:

  1. Add an OAuth Client in your SAP Cloud Platform instance of SAP Jam Collaboration, and copy the OAuth2 access token.

  2. In the SAP Jam Collaboration OData API Reference, paste the OAuth2 access token that you copied in the previous step into the OAuth2 token field in the top-middle banner of the page.

  3. In the content section, click Show Options to reveal the Query Parameters section for the API endpoint that you want to try out and fill in the available fields.

    Note:

    • You must fill any ID fields with valid IDs.
    • You must fill any text box labeled with the API endpoint’s entity type (Group, Event, etc.) with the required request payload for that endpoint.
    • You may use any allowed service query options by correctly filling in their text boxes. (See OData Query Parameters for details.) If you do not set these options, they will not be used.
    • You may select the response format that you want returned (JSON or XML). If you do not select this option, the API Reference default of the JSON format will be set.
  4. Click Try. The API call will run immediately, and a pop-up window will display the response.


Updated 05/03/2018

Time to Complete

15 Min

Beginner

Tags

Next
Back to top