The documentation in this page corresponds to the original version of the PSICQUIC specification.
Using SOAP is the traditional way to access a web service. The PSICQUIC specification defines a standard WSDL that all the implementations must comply with. This file contains the list of web service methods available for users.
The SOAP URL for the different interaction databases can be found in the Registry. To fetch the WSDL just append ?wsdl to the SOAP URL (example).
Important note: the maximum number of interactions that can be returned by a SOAP request is 200. If you want to retrieve more results, do an iteration of requests incrementing the firstResult parameter by 200 until you reach the total number of results.
| Method Name | Description |
|---|---|
| getByQuery | Retrieve data using a MIQL query |
| getByInteractor | Retrieve data using a specific participant identifier |
| getByInteractorList | Retrieve data using a list of participant identifiers. This method can be used to retrieve interactions where the two or more participants passed as arguments are found. To do so, set the operand to AND. |
| getByInteraction | Retrieve a specific interaction using its identifier |
| getByInteractionList | Retrieve a list of interactions, using the identifiers |
Other methods to retrieve information about the service itself (metadata) are also available:
| Method Name | Description |
|---|---|
| getSupportedReturnTypes | Returns the list of possible formats for the retrieved data |
| getSupportedDbAcs | Supported database accessions |
| getVersion | Gets the version of the service |
This section explains the parameters that can be used in the above methods.
Description: Retrieves data using a MIQL query. This is the more general method an can be used to perform the most flexible queries by using MIQL. The other methods of the web service are just convenience methods that just reduce the scope of the query, hence what the other methods do can be done through this one.
Input parameters:
| Name | Type | Required | Description | Example(s) |
|---|---|---|---|---|
| query | String | Yes | The MIQL query to use | |
| infoRequest | infoRequest | Yes | Used to describe the format our to define the pagination |
Output parameters:
| Name | Type | Description |
|---|---|---|
| queryResponse | queryResponse | Complex object containing the resulting data and some metadata about the results |
Description: Retrieves data using a specific participant identifier.
Input parameters:
| Name | Type | Required | Description | Example(s) |
|---|---|---|---|---|
| dbRef | dbRef | Yes | The identifier to search for | |
| infoRequest | infoRequest | Yes | Used to describe the format our to define the pagination |
Output parameters:
| Name | Type | Description |
|---|---|---|
| queryResponse | queryResponse | Complex object containing the resulting data and some metadata about the results |
Description: Retrieve data using a list of participant identifiers. This method can be used to retrieve interactions where the two or more participants passed as arguments are found. To do so, set the operand to AND.
Input parameters:
| Name | Type | Required | Description | Example(s) |
|---|---|---|---|---|
| dbRefs | List of dbRef | Yes | The identifiers to search for | |
| infoRequest | infoRequest | Yes | Used to describe the format our to define the pagination | |
| Operand | String | No | When multiple identifiers are provided two options are possible, dependening if we want to (a) find the interaction where ALL the provided identifiers are found or (b) just get a list of interactions where ANY of the identifiers is found. For (a) the value of operand is 'AND', whereas for (b) is 'OR' (default) | AND, OR |
Output parameters:
| Name | Type | Description |
|---|---|---|
| queryResponse | queryResponse | Complex object containing the resulting data and some metadata about the results |
Description: Retrieves a specific interaction using its identifier. This method is identical to the getByInteractor, but requiring interaction accessions instead.
Input parameters:
| Name | Type | Required | Description | Example(s) |
|---|---|---|---|---|
| dbRef | dbRef | Yes | The identifier to search for | |
| infoRequest | infoRequest | Yes | Used to describe the format our to define the pagination |
Output parameters:
| Name | Type | Description |
|---|---|---|
| queryResponse | queryResponse | Complex object containing the resulting data and some metadata about the results |
Description: Retrieves a list of interactions, using the identifiers.
Input parameters:
| Name | Type | Required | Description | Example(s) |
|---|---|---|---|---|
| dbRefs | List of dbRef | Yes | The identifiers to search for | |
| infoRequest | infoRequest | Yes | Used to describe the format our to define the pagination |
Output parameters:
| Name | Type | Description |
|---|---|---|
| queryResponse | queryResponse | Complex object containing the resulting data and some metadata about the results |
| Name | Type | Required | Description | Example(s) |
|---|---|---|---|---|
| id | String | Yes | Identifier to use | brca2 P12345 |
| dbAc | String | No | Accession number of the database. Use it to avoid ambiguity if two databases contain the same parameter. Rarely used and not supported throughout |
| Name | Type | Required | Description | Default |
|---|---|---|---|---|
| resultType | String | No | Format of the returned results. Possible options are: 'psi-mi/tab25' (default): MITAB 25 format. 'psi-mi/xml25': PSI-MI XML 2.5.4 format. 'count': just contains the result counts. |
psi-mi/tab25 |
| firstResult | Integer | No | Index for the first returned value (offset) | 0 |
| blockSize | Integer | No | Number of results to be returned. Maximum is 200, so higher values will be ignored. | 0 |
When doing queries, the results must be paginated to avoid memory problems. All methods accept the parameters firstResult and blockSize, which are used to define the starting interaction and the number of interactions to be retrieved. Use them to retrieve your data in batches.
| Name | Type | Description |
|---|---|---|
| resultSet | resultSet | Contains the results of the query |
| resultInfo | resultInfo | Information about the query, such as the total number of results found |
| Name | Type | Description |
|---|---|---|
| mitab | String | When the psi-mi/tab25 format is used, this element contains the resulting data as a String in MITAB format. Lines are separated by a carriage return. |
| entrySet | PSI-MI XML 2.5 | When the psi-mi/xml25 format is used, the XML file with the results is embedded in the response |
| Name | Type | Description |
|---|---|---|
| firstResult | Integer | The offset used when querying the service |
| blockSize | Integer | The number of results returned. If the service returns a different number of results than those asked for (e.g. the number provided was higher than the server maximum), this value shows how much data was returned by the service |
| totalResults | Integer | The total number of interaction evidences found, irrespectively of the firstResult and blockSize. |
To query the SOAP service specific libraries may be needed by your programs. There is a JAVA client already implemented, but if you are not using JAVA you may need to create the service yourself (and if it is generic, contributing it to the project would be great!).
When doing queries, the results must be paginated to avoid memory problems. All methods accept the parameters firstResult and maxResults, which are used to define the starting interaction and the number of interactions to be retrieved. Use them to retrieve your data in batches. If they are not specified, the web service will limit the results automatically. Note that this would happen too if you set a value of maxResults higher than a defined threshold, which in the Reference Implementation is 200.
The default return types are:
- psi-mi/tab25: returns PSI-MI TAB 2.5 format.
- psi-mi/xml25: returns PSI-MI XML 2.5.4 format.