Client API

Go Up to API Reference

This part of the ER/Studio Team Server API lets allows you to work with clients that use the API.

GET v1/clients/<id>

Obtains information about the client application with the specified ID.

If successful, the response from the server provides the following fields:

• clientId
• type
• url
• name
• description
• clientType
• createdAt
• subType (provides details of Term Type)
• nativeType (only if clientType is 1)
• modifiedAt (only if modified after creation)
• home (optional)
• image (optional)
• redirectURL (optional)
• stewards (optional)

POST v1/clients

Registers a client application in ER/Studio Team Server. See Registering Your API Client Application in ER/Studio Team Server.

Your request must provide the following fields:

Note: The specified "clientId" and "secret" must be those that you previously registered by email with Embarcadero.

• clientId
• secret
• name
• description
• clientType
• subType (optional when creating a Term, can be used to set the Term Type)
• nativeType (only if clientType is 1)
• home (optional)
• image (optional)
• redirectURL (optional)
• stewards (optional)

If successful, the response from the server provides the parameters of the request (with the exception of the secret of your client application), in addition to the following fields:

• type
• url

PUT v1/clients/<id>

Updates the metadata of your client application.

Your request must provide the following fields:

• name
• description
• clientType
• nativeType (only if clientType is 1)
• subType (optional when updating a Term, can be used to set the Term Type)
• home (optional)
• image (optional)
• redirectURL (optional)
• stewards (optional)

You must set every property, including those properties that you do not wish to change, otherwise they are removed from the client entry.

If successful, the response from the server provides the same fields as a GET response.

DELETE v1/clients/<id>

Deletes the client application with the specified ID.

If successful, the response is "client is deleted".

Fields

Client API requests and responses can include any combination of the following fields:

Item	Example	Description
"clientId"	"6a2a39ba-9688-493d-b348-187468f599ae"	An UUID that uniquely identifies your client application.
"secret"	"a28e0ca4-27cb-4361-bf97-3b26c612d66a"	The secret of your client application.
"name"	"My App"	The name of your client application.
"description"	"My custom API client application"	A description of your client application.
"clientType"	1	The type of your client application, which can be any of the following: Web Application (0). Native Application (1).
"nativeType" (optional)	4	If "clientType": 1, this property specifies which platform your client application supports, which can be any of the following: Windows (0). Mac OS X (1). Android (2). iOS (3). Other (4).
"home"	"http://myapp.example.com"	The home page of your client application.
"image"	"http://myapp.example.com/logo.png"	A direct link to an image that represents your client application.
"redirectURL"	"http://myapp.example.com/oauthcallback"	The OAuth callback URL of your client application.
"stewards"	[ { "name": "Jane" }, { "name": "John" } ]	A list with the username of EDN users that are stewards of your client application.
"createdAt"	"2013-06-21"	The date when you registered your client application in the ER/Studio Team Server installation, in ISO 8601 format.
"modifiedAt"	"2013-06-24"	The date when you last modified the metadata of your client application, in ISO 8601 format.
"type"	"client"	The type of the resource. Its value is always "client" for Client API resources.
"url"	"http://myapp.example.com/api/v1/clients/6a2a39ba-9688-493d-b348-187468f599ae"	URL that you can use to update, delete and get your client application data from the API.

Example Response

This is an example response from a GET call:

{
    "client": {
        "clientId": "6a2a39ba-9688-493d-b348-187468f599ae",
        "name": "My App",
        "description": "My custom API client application",
        "clientType": 0,
        "nativeType": 0,
        "createdAt": "2013-06-21",
        "type": "client",
        "url": "http://localhost:8080/api/v1/clients/6a2a39ba-9688-493d-b348-187468f599ae",
        "modifiedAt":"2013-06-24"
    }
}

Errors

You might run into any of the following errors when using this API:

HTTP Status Code	Response	Description
400 Bad Request	<field name> field is required	Your request did not include the specified required field. Repeat your request including the specified field.
	clientType or nativeType field must be number	Your request specified a value for "clientType" or "nativeType" that is not a number. These fields must be positive integers. See in the documentation above a list of possible values for both.
	clientType value is not valid. Expect number from 0 to 1 to represent [webApplication(0),installApplication(1)]	Your request specified a value for "clientType" that is not valid. Valid values are: 0 (web application) 1 (native application)
	nativeType value is not valid. expect number from 0 to 4 to represent [Window(0),Mac(1),Android(2),iOS(3),Other(4)]	Your request specified a value for "nativeType" that is not valid. Valid values are: 0 (Windows) 1 (Mac OS X) 2 (Android) 3 (iOS) 4 (other)
	The Client already exists with the given id.	You are trying to register (POST v1/clients) a client with a client ID that is already registered on the target ER/Studio Team Server installation. Use PUT v1/clients/<id> instead, if you want to modify a registered client application entry.
	The to be updated client is not found.	You are trying to update (PUT v1/clients/<id>) a client with a client ID that is not registered on the target ER/Studio Team Server installation.
401 Unauthorized	<oauth> <error_description>Full authentication is required to access this resource</error_description> <error>unauthorized</error> </oauth>	You do not need authorization to access /v1/clients. Check that you wrote the URL address correctly. Example of valid URL: http://teamserver.example.com/api/v1/clients
404 Not Found	client not found	You are trying to delete (DELETE v1/clients/<id>) a client with a client ID that is not registered on the target ER/Studio Team Server installation.
405 Method Not Allowed	Request method '<method>' not supported	If you get this error: Check that the request method you used is allowed. Make sure you are using the right method (GET, POST, PUT, DELETE) for the API you access. For example, you cannot request GET v1/clients or POST v1/clients/<id>. If you are using a POST v1/clients or PUT v1/clients/<id> request, you may have forgotten to include in your request the Content-Type HTTP header defined with the value application/json.
415 Unsupported Media Type		You probably forgot to include in your request the Content-Type HTTP header defined with the value application/json.
500 Internal Server Error	Internal Server Error	If you receive this error, repeat your request with the same parameters, to ensure that this is not a random error. If the error persists: If you are using the GET v1/clients/<id>, check that the specified client application ID is correct. Try to register the specified client ID; if the registration completes successfully, it means that you were using an unregistered client application ID. Check that you are using the right JSON type for each variable. For example, check that you are not providing an integer (1234) in a field that expects a string ("1234"). If the issue persists, please contact the administrator of your ER/Studio Team Server installation.

See Also

• Registry API
• OAuth 2.0 API