App LoginSupport CenterProduct UpdatesOAS JSON

Using Postman

How to Use Postman to Integrate with ClearPoint Strategy's OpenAPI 3.0 Specification

Suggest Edits

📘

If you're ready to start exploring more complex integrations with ClearPoint, Postman will quickly become your BFF.

Why Do Developers Love Postman?

Well, imagine Gru from "Despicable Me" unveiling his next big heist plan, but instead of stealing the moon, he's trying to test an API. As he dramatically unveils his tool of choice, it's... Postman! Meanwhile, the Minions go bananas in the background, chanting "Post-man! Post-man!" because even in their mischievous world, they know that a solid API testing tool is more valuable than a shrink ray.

After all, you might not always need to steal the moon, but you'll always need to test your APIs! 🌙📬😂

Prerequisites

Import the OpenAPI 3.0 Specification

One of the coolest things about Postman is its ability to automatically import OAS (OpenAPI Specification) documents and create collections from them. This way, you can run (and save) commands against the ClearPoint API and test out your logic before integrating it into your application.

  1. Launch Postman: Start the Postman application on your computer.

  2. Click on the 'Import' button: This is located at the top left corner of the main Postman window.

  3. Select 'Link' tab: In the import dialog, select the 'Link' tab.

  4. Enter the URL of the ClearPoint Strategy's OpenAPI 3.0 Specification: Paste the ClearPoint OAS URL into the input box. (Click here to get a link to the most recently published version.)

  5. Click 'Continue': Postman will fetch the specification and provide a preview.

  6. Confirm Import: Confirm by clicking 'Import' to finalize the import process.

Benefits of Importing the Specification

  1. Seamless Integration: By understanding the API endpoints, methods, and structures, customers can ensure a smoother integration process with their existing systems.

  2. API Exploration: Postman's interactive interface allows users to send test requests, providing clarity on the expected inputs and outputs.

  3. Debugging and Validation: Before deploying the integration to a live environment, customers can test and validate their calls within Postman, ensuring everything works as expected.

  4. Documentation at Your Fingertips: Postman's visual representation can serve as interactive documentation, ensuring accurate implementation.

  5. Collaboration: Share the imported Postman collection with your team, making sure everyone involved in the integration process is aligned.

Authenticating with ClearPoint in Postman

Setting up authentication in Postman to connect to the ClearPoint Strategy API using OAuth 2.0 with the Authorization Code (with PKCE) grant type can be accomplished using the following steps:

  1. Open Postman: Begin by opening your Postman application.

  2. Select or Create a Request: You can either create a new request or choose an existing one.

  3. Authorization Tab: Go to the "Authorization" tab of your request. In the "Type" dropdown, select "OAuth 2.0".

  4. Configure OAuth 2.0 Settings: Under the section for configuring OAuth 2.0, fill out the following fields:

    • Header Prefix: Enter "Bearer".
    • Grant Type: Select "Authorization Code (With PKCE)" from the dropdown list.
    • Callback URL: Typically, Postman uses https://oauth.pstmn.io/v1/callback as a default callback.
    • Auth URL: https://app.clearpointstrategy.com/oauth2/token
    • Access Token URL: https://app.clearpointstrategy.com/oauth2/token
    • Client ID: You can enter anything you would like here, like postman.
    • Client Secret: This can be left blank as we're using the PKCE grant type.
    • Scope: This can be left blank as the application grants scope based on your user type and permissions.
    • Client Authentication: Select "Send client credentials in body."

  5. Request Token: Click the "Get New Access Token" button. This should open a new window where you can log in to ClearPoint Strategy.

  6. Authenticate & Authorize: After entering your ClearPoint Strategy credentials, you should be prompted to authorize the application (Postman) to access your ClearPoint Strategy data. Allow the necessary permissions.

  7. Use Token: Once you've authorized the application, Postman should receive the access token. You can then use this token in your requests to the ClearPoint Strategy API. If "Add token to" is set to "Header", Postman will automatically add the Authorization header with the "Bearer" prefix and the received token to your requests.

  8. Make a Request: With the token set, go to the "Body" tab of your request and set up the necessary parameters. Then, send the request to the desired endpoint of the ClearPoint Strategy API.

  9. Refresh Token: OAuth tokens usually have an expiration time. If your token expires, you might need to refresh it. Configure the refresh token settings if necessary and provided by ClearPoint Strategy.

That's it! You've set up authentication in Postman to connect to the ClearPoint Strategy API using OAuth 2.0 with the Authorization Code (with PKCE) grant type. Always remember to handle tokens with care, avoid sharing them, and store them securely when not in use.

Simple Integration Examples

Please note that you will need to have set up authentication first in order to try these out.

1. Create a new measure (POST)

Endpoint:

POST https://app.clearpointstrategy.com/api/v1/measures

Body:

{
  "name": "Revenue Growth",
  "scorecardId": 1,
  "ownerId": 12345,
  "collaborators": [12346, 12347],
  "hiddenPeriods": [],
  "tags": [1, 2, 3],
  "externalApplication": "FinanceApp",
  "externalObject": "RevenueTable",
  "externalObjectId": "RT123"
}

2. Edit an existing measure (PUT)

To edit an existing measure, you'll need its measureId.

Endpoint:

PUT /api/v1/measures/{measureId}

Replace {measureId} with the actual ID of the measure you want to update. For example, if measureId is 1001, the endpoint becomes PUT /api/v1/measures/1001.

Body:

{
  "name": "Updated Revenue Growth",
  "scorecardId": 2,
  "ownerId": 12348,
  "collaborators": [12349],
  "tags": [4, 5],
  "externalApplication": "UpdatedFinanceApp",
  "externalObject": "UpdatedRevenueTable",
  "externalObjectId": "URT123"
}

3. Delete a measure (DELETE)

To delete an existing measure, you'll also need its measureId.

Endpoint:

DELETE /api/v1/measures/{measureId}

Replace {measureId} with the actual ID of the measure you want to delete. If measureId is 1001, the endpoint becomes DELETE /api/v1/measures/1001. No body content is required for the DELETE command.

These are basic examples based on the provided schema. In real-world usage, it would be crucial to always refer to official API documentation and also make sure proper authentication is in place before making any API requests.

Conclusion

For customers wanting to integrate their systems with ClearPoint Strategy, Postman offers an invaluable platform for understanding, testing, and preparing for the integration. Importing ClearPoint Strategy's OpenAPI 3.0 specification simplifies the process, ensuring a successful and efficient integration.

Updated 8 months ago