Fetching available service providers via the API

The API provides a mechanism to request a list of service providers for a given user account such as would be used in a portal-type application. The call returns a list of the providers listed in the non-expired permission sets assigned to the account. Since appearing in a permission set does not guarantee access, either the application or the permission sets need to be maintained in line with active subscriptions to those resources.

Prerequisites

To fetch the service providers available to an account, a client application must

authenticate to the API as described in Authenticating to the API.
query for an account or follow an account link from another API object, or as the result of creating a new account.

Procedure

Follow the link from an account with a application/vnd.eduserv.iam.serviceList-v1+json object by performing a GET request to the following URL:

/api/v1/example.org/account/<id>/services

Where id is the value of the id field for the account object.

Response codes

HTTP Response Code	Description
200	The request was successful.
404	The account does not exist.
403	The requester does not have permission to perform this operation.

Response payload

The response is an application/vnd.eduserv.iam.serviceList-v1+json object. The service list resource also provides an Atom 1.0 representation with a media type of application/atom+xml.

application/vnd.eduserv.iam.serviceList-v1+json object

Object field

Description

services

An array of objects containing a service. Each service has the following fields:

id
title
link
description
tags

Example

CODE

Request:
GET /api/v1/example.org/account/1234567/services HTTP/1.1
Authorization: OAApiKey <api-key>
Response:
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.serviceList-v1+json


{
   "services" : [
    {
      "id" : "http://service.com/id1",
      "title" : "Service number one",
      "description" : "Amazing service number one",
      "link" : "http://example.com/one",
      "tags" : ["tag1", "tag2"],
    },
    {
      "id" : "http://service.com/id2",
      "title" : "Service number two",
      "description" : "Incredible service number two",
      "link" : "http://example.com/two",
      "tags" : ["tag3", "tag4"],
    }
  ]
}