ServiceRoles

Resource URI

/services/{serviceId}/roles

Items in curly braces represent variables.

Description

Service Roles establish a connection between Services, Roles, and through Roles, Users, and thus determine what a User, or Member of the Developer Portal, can see when interacting with API-related Portal pages such as I/O Docs.

Resource Schema

Property	Characteristics
id	Type	string
	Sub-type
	Create Rule	Ignored
	Update Rule	Required (if not in context)
	Fetch Rule	Implicit
	Description	Object identifier.
created	Type	string
	Sub-type	datetime
	Create Rule	Ignored
	Update Rule	Ignored
	Fetch Rule	Implicit
	Description	Date/time the object was created.
updated	Type	string
	Sub-type	datetime
	Create Rule	Ignored
	Update Rule	Ignored
	Fetch Rule	Implicit
	Description	Date/time the object was updated.
name	Type	string
	Sub-type
	Create Rule	Required
	Update Rule	Optional
	Fetch Rule	Implicit
	Description	Role name.
action	Type	string
	Sub-type
	Create Rule	Required
	Update Rule	Optional
	Fetch Rule	Implicit
	Description	Action.

fetch all [GET]

Retrieves all Roles currently assigned to the identified Service Definition.

Parameters

Parameter	Required	Type	Description
serviceId	true	string	Service identifier.
fields	false	string	Comma-separated list of property paths to include in response. Each property path is a dot-separated list of object property names. fields=<property\[.property...\]>\[,...\]\[&fields=...\]
filter	false	string	Colon-separated name/value pair specifying the name of property whose value must contain the given value (as a substring). Results may also be filtered by nested collections' properties by specifying a dot-separated property path. filter=<property\[.property...\]>:<value>\[&filter=...\]
sort	false	string	Comma-separated list of properties to sort by. Only root-level properties are supported. Each property name may be optionally followed by :asc or :desc to specify sort direction (defaults to asc). sort=<property\[:(asc\|desc)\]>\[,...\]\[&sort=...\]
limit	false	int	Number of objects to return in the result. Defaults to 100.
offset	false	int	0-based index of first object in the list to return. Defaults to 0.

Returns

Success

Array of Service Roles If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/services/<INSERT serviceId HERE>/roles' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "updated": "2020-01-24T22:53:21.000+0000",
        "created": "2020-01-24T22:23:42.000+0000",
        "action": "read",
        "name": "Administrator",
        "id": "5601aa8e-7401-489f-8641-352405508576"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/services/<INSERT serviceId HERE>/roles' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "updated": "2020-01-25T22:53:21.000+0000",
        "created": "2020-01-25T22:23:42.000+0000",
        "action": "read",
        "name": "Administrator",
        "id": "5601aa8e-7401-489f-8641-352405508576"
    },
    {
        "updated": "2020-01-24T22:53:21.000+0000",
        "created": "2020-01-24T22:53:21.000+0000",
        "action": "read",
        "name": "API Manager",
        "id": "5c732e56-ff77-4eba-92ee-4f9a57e92355"
    }
]

update [PUT]

Assigns roles to the identified Service Definition.

You can add multiple {"id":"RoleId","action":"read"} objects to the roles array to add as many assigned roles to the Service Definition as needed.

Parameters

Parameter	Required	Type	Description
serviceId	true	string	Service identifier.
serviceRole	true	object	Service Role object

Returns

Success

ServiceDefinition as persisted If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/services/<INSERT serviceId HERE>' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"roles":[{"id":"<INSERT THE roleId FOR THE ROLE TO BE_ASSIGNED TO THE IDENTIFIED SERVICE DEFINITION HERE>","action":"read"}]}'

Response

[
    {
        "id": "20bf9ab5-ae07-4728-837b-effa98e46f17",
        "created": "2014-02-17T17:52:01.000+0000",
        "updated": "2014-05-27T17:53:26.000+0000",
		"version": "",
        "name": "API Service Definition Name"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/services/<INSERT serviceId HERE>' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"roles":[{"id":"<INSERT RoleId 1 HERE>","action":"read"},{"id":"<INSERT RoleId 2 HERE>","action":"read"}]}'

Response

[
    {
        "id": "c426638d-ba7d-4e64-b0e0-f7bc3a1a20c4",
        "created": "2014-04-06T20:48:58.000+0000",
        "updated": "2013-09-02T07:08:24.000+0000",
		"version": "",
        "name": "API Service Definition Name"
    }
]

delete [PUT]

Deletes all of the Roles assigned to the identified Service Definition.

To use the delete function you simply include an empty roles array {"roles":[]} .

Parameters

Parameter	Required	Type	Description
serviceId	true	string	Service identifier.

Returns

Success

ServiceDefinition as persisted If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/services/<INSERT serviceId HERE>' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"roles":[]}'

Response

[
    {
        "id": "c426638d-ba7d-4e64-b0e0-f7bc3a1a20c4",
        "created": "2014-04-06T20:48:58.000+0000",
        "updated": "2013-09-02T07:08:24.000+0000",
		"version": "",
        "name": "API Service Definition Name"
    }
]