© 2018 Capita Business Services Ltd. All rights reserved.

Capita Education Software Solutions is a trading name of Capita Business Services Ltd. Our Registered office is 30 Berners Street, London, W1T 3LR and our registered number is 02299747. Further information about Capita plc can be found in our legal statement.

Using Postman with Swagger Documented Endpoints

Postman and Swagger documented endpoints

API Documentation for SIMS Primary is available to potential integrators wishing to integrate with SIMS Primary.  It is recommended to use Postman to interact with the APIs documented features.

Exploring SIMS Primary APIs.

As implementation of the 'try out' feature in the documentation site (Swagger) is currently unavailable, as an alternative tool, we suggest use of Postman ( https://www.getpostman.com/) to try out the API calls. (Visit https://www.getpostman.com/docs/ for guidance on how to use Postman.)

Please refer our terms and conditions of use.

Access Token Requests and API Calls

In order to call the APIs successfully,

  1. Partners will require to request for an access token from the identity server.
    Once generated, a token will be valid only for an hour, therefore partners will need to generate a new token when the token in use expires.
  2. Partners will need to pass the access token (while it is valid) as 'authorising header' in the API request.

Overview of the Process

 

1. In Postman, open a new tab and set the request type to POST

2. Header: 

  • Content-Type: application/x-www-form-urlencoded

3. Body

  • Switch to 'raw'
  • Paste (replace the variables accordingly copying values from relevant client details):

For calling FreemiumAPI endpoints - Freemium Client Details must be used:

grant_type=client_credentials&client_id= {{client_id}}&client_secret={{client_secret}} &scope=partnerserverapplication partner

For calling ContractedAPI endpoints - Contracted Client Details must be used:

grant_type=client_credentials&client_id= {{client_id}}&client_secret={{client_secret}} &scope=partnerserverapplication partner&acr_values=orgselected: {{organisation_id}}

4. Press 'Send'

  • An access token is returned.

5. Copy the access token

6. Open a new tab and set the request type to GET

7. Add the headers

  • Authorization- paste-in the copied token: 'Bearer {{token}}'
  • Ocp-Apim-Subscription-Key- copy subscription key present with the relevant client details and paste

8. Enter the request URL starting with the relevant API endpoint

Freemium: https://pmapis.azure-api.net/sp-api-partner-dev

Contracted: https://pmapis.azure-api.net/sp-api-partner-live

9. Press 'Send' to request for data.

 

Steps with Postman Screen Captures

 

postman token request

 

1. Open a new tab and set the request type to POST

 

Postman Authorisation screen
Postman Authorisation Screen

 

2. Click on 'Headers' tab

  • Add Header - Content-Type:application/x-www-form-urlencoded
Postman Headers
Postman headers tab

3. Click on 'Body' tab

  • Select 'raw'
  • For requesting an access token to call:

FreemiumAPI endpoints - Freemium Client Detailsmust be used:

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=partnerserverapplication partner

ContractedAPI endpoints - Contracted Client Detailsmust be used:

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=partnerserverapplication partner&acr_values=orgselected:{{organisation_id}}
  • Replace the variables accordingly copying values from relevant client details.
Postman Variable
Postman - replace variable

NB: simsserverapplication should be changed to partnerserverapplication in the above.

  • Alternative to selecting 'raw', select 'x-www-form-urlencoded' and enter below keys & values from relevant client details:
grant_type:client_credentials

client_id: {{client_id}}

client_secret: {{client_secret}}

scope:partnerserverapplication partner

acr_values:orgselected: {{organisation_id}} - not required with Freemiumclients
Postman5
Postman screenshot

NB: simsserverapplication should be changed to partnerserverapplication in the above.

 

4. Press send to request the access token

Postman access token request
Postman access token request

5. Copy the access token

6. Open a new tab and set the request type to GET

7. Add the headers

  • Authorization- paste-in copied token: 'Bearer {{token}}'
  • Ocp-Apim-Subscription-Key- copy subscription key present with the relevant client details and paste
Postman-headers
Postman-headers

8. Enter the request URL starting with the relevant API endpoint

Freemium: https://pmapis.azure-api.net/sp-api-partner-dev

e. g.: https://pmapis.azure-api.net/sp-api-partner-dev/V1/Learner/Learners?$expand=Personal

Contracted: https://pmapis.azure-api.net/sp-api-partner-live

e.g.: https://pmapis.azure-api.net/sp-api-partner-live/V1/Learner/Learners?$expand=Personal

9. Press 'Send' to request for data

Postman data request
Postman data request