Managing API requests and responses

How to manage API requests?

Requests and responses

Once you have authenticated you can start creating and sending HTTP requests which allow you to manage the resources. After sending a request, you will receive a response detailing the outcome of your request.

For example, the HTTP request below pertains to documents and the aim is to obtain the information about one document filed to TestProtocol1.

GET https://{client}-api.phlextmf.com/documents/v5/documents?filter=protocol in ('TestProtocol1')&limit=1

In the result’s excerpt below there is one document returned for "TestProtocol1" together with the detailed information about it. The status “200 OK” should be displayed to inform you that the request has been successful.

{
    "data": [
        {
            "id": 900000000279,
            "filename": "AOJ-900000000279-D-doc1",
            "nativeFileName": "AOJ-900000000279-D-doc1-original.pdf",
            "fileSize": 388468,
            "mimeType": "application/pdf",
            "metadata": [
                {
                    "id": 110000043115,
                    "attributeId": -15,
                    "attributeDisplayName": "Added By User",
                    "value": "[email protected]",
                    "sortOrder": null,
                    "description": null,
                    "helpContent": null,
                    "processHelpContent": null,
                    "processHelpLink": null,
                    "status": 0
                }
            ]
        }
    ]
}

Where multiple values are returned, the data will be either returned as an array or encapsulated in an ApiPagedListResult node, depending on the purpose of the endpoint.

The below example shows data encapsulated in an ApiPagedListResult node:

GET https://{client}-api.phlextmf.com/attributes/v5/attributes/protocol/values

The response is 200 OK and the body of the response is as follows:

{
  "data": [
    {
      "id": 8,
      "attributeId": 5,
      "attributeDisplayName": "Protocol",
      "attributeRefName": "PROTOCOL",
      "attributeFieldName": "protocol",
      "value": "TestProtocol1",
      "status": 1
    },
    {
      "id": 9,
      "attributeId": 5,
      "attributeDisplayName": "Protocol",
      "attributeRefName": "PROTOCOL",
      "attributeFieldName": "protocol",
      "value": "TestProtocol2",
      "status": 1
    },
    ...
  ],
  "paging": {
    "offset": 0,
    "limit": 100,
    "totalItemCount": 21
  }
}

If there is no data to be returned when performing a search request, the response should be a 200 OK with an empty ApiPagedListResult node:

GET https://{client}-api.phlextmf.com/attributes/v5/attributes/protocol/values?filter=value eq 'DoesNotExist'

{
  "data": [],
  "paging": {
    "offset": 0,
    "limit": 100,
    "totalItemCount": 0
  }
}

If there is no data to be returned when performing a GET by the identifier, the response should be a 404 Not Found:

GET https://{client}-api.phlextmf.com/attributes/v5/attributes/protocol/values/1234

{
  "errorType": "RESOURCE_NOT_FOUND",
  "message": "The metadata value requested was not found",
  "exception": null
}

HTTP requests

An HTTP request is necessary to perform an API call.

HTTP requests consist of:

HTTP verb
URI link
Filters or sorting if applicable

HTTP verbs

The selection of the HTTP verb defines the action to be performed.

There are four most commonly used HTTP verbs:

GET - retrieve a resource or a collection of resources, for example, generate reports, lists of attributes or documents.
POST - create a resource, or retrieve a collection of resources using complex filters, (see URL Length below), for example, create a placeholder, site, country etc.
PUT - update a resource, for example, update Vendor, a user account.
DELETE - delete a resource, for example, delete a site.

URI link

URI link is used to target the resources to be accessed and managed.

The structure of the URI link:

alt text

The PhlexTMF API is structured into several different sections depending on the resource being accessed. The collection name helps you specify this section.

API	Description
Authorisation	Used for logging in and acquiring a JSON web token for API requests.
Attributes	The set of metadata that can be associated with documents, for example sites, countries and protocols. The Attributes API enables the retrieval of these attributes and the creation, modification and retrieval of their values within the system.
Documents	An API for creation and management of documents within the PhlexTMF system.
Milestones	Milestones are a representation of key dates against entities within the system. Only certain objects (namely sites, protocols and countries) are permitted to have milestones, which are used in completeness reporting and understanding expected dates for documents. The Milestones API allows the update and retrieval of an object's milestones and milestone types.
Events	Events allow for the registration of additional expected documentation within the system, for example when new site personnel are employed in a study or when protocols are amended. Only certain objects (namely sites, protocols and counties) are permitted to have events raised against them and the event types must already exist within the system. The Events API allows for the retrieval of event types and the creation of events.
Reports	PhlexTMF reporting can present information on study-specific content, user activity or business-related performance. Users access the appropriate data with standard system-generated reports, or from lists generated in the Documents screen. All reports can be saved to enable you to rerun your favourite reports without having to redefine them each time, and their content exported to Excel for further analysis and comparison.

Finally, you can also append other elements to your URI link such as the filters.

HTTP status codes, errors and request validation

If your request is not successful, an error will be returned within:

the 4xx range if an error is caused by the user
the 5xx range if an error is caused by the server.

The JSON response body will include an array of validation/error messages.

For example an error might return:

Error Type: A machine readable and consistent type e.g. INTERNAL_ERROR, ACCOUNT_USER
Error Feedback: A human readable explaining the error type.
Exception: Exception data if application

Validation errors will return:

Field: Associated model field for which the validation error is associated e.g DocumentDate
Criteria: Description of qualifying valid criteria. Dates must be in the format dd/MMM/YYYY e.g. 30/JUL/1966
Validation Error Type: A machine readable and consistent validation error type e.g. INVALID_DATE_FORMAT
Message: A human readable message explaining the error e.g. The date format entered is invalid.

Our standard validation codes

Validation Error Type	Description
REQUIRED_FIELD_MISSING	Required data missing
MAX_LENGTH_EXCEEDED	The data supplied exceeded the allowed length.
INVALID_DATE_FORMAT	The date supplied is provided in an invalid format.
INVALID_DATE_RANGE	The date supplied is outside of the permitted range. For example if the date specified is in the past yet past values aren’t allowed.
INVALID_NUMBER_FORMAT	A number provided is in an invalid format. For example if decimal numbers weren’t permitted.
INVALID_NUMBER_RANGE	The number provided is out of the allowed range. For example if negative numbers weren’t permitted.
INVALID_FORMAT	General format error.
ID_VALUE_MISMATCH	Some requests may support ID and value. For example UserId and Email, before using the ID (UserId) and Value (Email) must correlate.
METADATA_RULE_VIOLATION	Metadata submitted doesn’t pass business rule validation. For example an Artifact may imply a specific Sub-Artifact, attempting to supply an invalid Sub-Artifact would imply a rule violation.
UNKNOWN_RESOURCE	Request refers to resources which do not exist or do not have access to see.
UNSUPPORTED_FILTER_SYNTAX	The filter parameter supplied has syntax not supported. For example document querying does not currently support OR based filtering.
INVALID_FILTER_SYNTAX	The filter parameter supplied is invalid. For example “name eq 'John Smith’” is valid however “name = ‘John Smith’” is invalid syntax.
UNSUPPORTED_ORDERBY_SYNTAX	The order by parameter supplied has a syntax not supported. For example some requests won’t support multiple column ordering.
INVALID_ORDERBY_SYNTAX	The order by parameter supplied is invalid. For example “name asc” is valid however “name ascending” would be invalid.
DUPLICATE_METADATA	Duplicate metadata items have been supplied whereby only one is permitted.
METADATA_ATTRIBUTE_NOT_FOUND	The metadata supplied does not match a known metadata attribute within the system.
INVALID_METADATA_OPTION	The metadata supplied isn't a valid option given other metadata restraints.
METADATA_SECURITY_VIOLATION	Metadata supplied is valid but not allowed based on the security configuration.

Our standard error codes

Code	Error Type	Description
401	AUTHENTICATION_FAILURE	The supplied information could not be authenticated. I.e. username/password incorrect
401	ACCOUNT_DISABLED	The account attempting to authenticate is disabled.
401	ACCOUNT_LOCKED	The account attempting to authenticate is locked.
401	ACCOUNT_PASSWORD_CHANGE_REQUIRED	The account attempting to authenticate is requires a password change.
401	INVALID_TOKEN	The JWT authentication token supplied is invalid.
403	NOT_AUTHORIZED	Access is not permitted based on the supplied authentication token.
404	RESOURCE_NOT_FOUND	The resource requested was not found
500	RESTORE_POINT_OPEN	Action cannot be undertaken as a restore point is open.
500	INTERNAL_ERROR	An error occurred e.g. unhandled error, network or database connectivity issues.

How to manage API requests?​

Requests and responses​

HTTP requests​

HTTP verbs​

URI link​

HTTP status codes, errors and request validation​

Our standard validation codes​

Our standard error codes​