Resource: External Systems ( /api/externalsystems )
This is a collection resource which allows the search and retrieval of all or a subset of external systems (Defect Trackers, Enterprise Architect connections etc.).
Root Relation: ExternalSystems
This resource supports the following methods: GET, POST
Methods
GET
Retrieves all (or a subset) of external systems.
This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.
Required Permissions
- Resources/ExternalLinks
Supported Expansions
- Configuration
- ExternalSystemLinks
- FieldValues
- Widgets
- AdditionalConfigurationLinks
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service - in addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
---|---|
200 - OK | Returned if the request was completed successfully. |
An example of retrieving all external systems.
Request Headers
Key | Value | Description |
---|---|---|
Accept | application/json |
Response Headers
Key | Value | Description |
---|---|---|
Content-Type | application/json; charset=utf-8 |
Response Body
{ "Skip": 0, "Top": 25, "Total": 2, "Items": [ { "Id": "744904d6-9612-4e87-a718-7b5d80c0060d", "OrganisationId": null, "Name": "Jira", "Type": "Jira", "ConnectionType": "Jira", "ConnectionString": "http://mycompany.com:8090/", "Enabled": true, "QualifiedName": null, "TypeDescription": null, "NumberOfLinks": 0, "Categories": [], "UserName": "remote", "HasPassword": true, "ConfigurationComplete": true, "ConfigurationProblems": [], "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d" }, { "Id": "a01fc7ed-3492-4792-9a0b-e2b52fa10913", "OrganisationId": null, "Name": "TFS", "Type": "TFS2010", "ConnectionType": "TFS2010", "ConnectionString": "http://tfs.mycompany.com:8080/tfs/Projects", "Enabled": true, "QualifiedName": null, "TypeDescription": null, "NumberOfLinks": 0, "Categories": [], "UserName": "remote_tfs", "HasPassword": true, "ConfigurationComplete": true, "ConfigurationProblems": [], "Self": "http://localhost/api/externalsystem/a01fc7ed-3492-4792-9a0b-e2b52fa10913" } ], "Self": "http://localhost/ExternalSystems" }
Status Code
200 - OK
An example of retrieving a set of external systems by type using the ODATA $filter query parameter.
Request Headers
Key | Value | Description |
---|---|---|
Accept | application/json |
Request Parameters
Key | Value | Description |
---|---|---|
$filter | Type eq 'Jira' | The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Type%20eq%20'Jira'. |
Response Headers
Key | Value | Description |
---|---|---|
Content-Type | application/json; charset=utf-8 |
Response Body
{ "Skip": 0, "Top": 25, "Total": 1, "Items": [ { "Id": "744904d6-9612-4e87-a718-7b5d80c0060d", "OrganisationId": null, "Name": "Jira", "Type": "Jira", "ConnectionType": "Jira", "ConnectionString": "http://mycompany.com:8090/", "Enabled": true, "QualifiedName": null, "TypeDescription": null, "NumberOfLinks": 0, "Categories": [], "UserName": "remote", "HasPassword": true, "ConfigurationComplete": true, "ConfigurationProblems": [], "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d" } ], "Self": "http://localhost/ExternalSystems?$filter=Type eq 'Jira'" }
Status Code
200 - OK
POST
Create a new external system.
Required Permissions
- Resources/ExternalLinks
Supported Expansions
- Configuration
- ExternalSystemLinks
- FieldValues
- Widgets
- AdditionalConfigurationLinks
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service - in addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
Status | Description |
---|---|
201 - Created | Returned if the request was completed successfully. |
An example of creating a new external system (without any additional field values).
Request Headers
Key | Value | Description |
---|---|---|
Content-type | application/json | |
Accept | application/json |
Request Body
{ "Type": "Jira", "Name": "Jira" }
Response Headers
Key | Value | Description |
---|---|---|
Location | http://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D | |
Content-Type | application/json; charset=utf-8 |
Response Body
{ "Id": "744904d6-9612-4e87-a718-7b5d80c0060d", "OrganisationId": null, "Name": "Jira", "Type": "Jira", "ConnectionType": "Jira", "ConnectionString": "http://mycompany.com:8090/", "Enabled": true, "QualifiedName": null, "TypeDescription": null, "NumberOfLinks": 0, "Categories": [], "UserName": "remote", "HasPassword": true, "ConfigurationComplete": true, "ConfigurationProblems": [], "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d" }
Status Code
201 - Created
An example of creating a new external system with full configuration supplied in field values.
Request Headers
Key | Value | Description |
---|---|---|
Content-type | application/json | |
Accept | application/json |
Request Parameters
Key | Value | Description |
---|---|---|
$expand | FieldValues | Include field values in response. |
Request Body
{ "Type": "Jira", "Name": "Jira", "FieldValues": { "Url": "http://mycompany.com:8090/", "UserName": "remote", "Password": "password", "IgnoreInvalidRemoteCertificates": false } }
Response Headers
Key | Value | Description |
---|---|---|
Location | http://localhost/api/externalsystem/744904D6-9612-4E87-A718-7B5D80C0060D | |
Content-Type | application/json; charset=utf-8 |
Response Body
{ "Id": "744904d6-9612-4e87-a718-7b5d80c0060d", "OrganisationId": null, "Name": "Jira", "Type": "Jira", "ConnectionType": "Jira", "ConnectionString": "http://mycompany.com:8090/", "Enabled": true, "QualifiedName": null, "TypeDescription": null, "NumberOfLinks": 0, "Categories": [], "UserName": "remote", "HasPassword": true, "ConfigurationComplete": true, "ConfigurationProblems": [], "FieldValues": { "Url": "http://mycompany.com:8090/", "UserName": "remote", "Password": "password", "IgnoreInvalidRemoteCertificates": false }, "Self": "http://localhost/api/externalsystem/744904d6-9612-4e87-a718-7b5d80c0060d" }
Status Code
201 - Created