Getting Started
Qodly provides a sophisticated REST server that facilitates direct access to data stored within Qodly applications. This functionality is enabled by default once proper configuration settings are applied.
Locating API Keys and Endpoint URLs
To effectively use the Qodly REST API, you will need to obtain the API Key and Endpoint URL, which are essential for authenticating and directing your API calls.
To fetch these credentials, please refer to the detailed steps in the API Keys section of this documentation.
Configuring Data Access
Access to dataclasses and their attributes is granted by default via the REST server, enhancing integration capabilities with external applications.
Managing Dataclass Exposure
To restrict access to sensitive dataclasses such as those containing user credentials, follow these steps:
- Open the Model Editor.
- Access the properties panel of the dataclass you intend to modify.
- Enable the
Do not Expose as REST
option within the Scope property.
![](/docs/assets/images/dataclass-exposeAsRest-4e60ecec0070c1205d615fef6b2da1cb.png)
Managing Attribute Exposure
By default, attributes within these dataclasses are also exposed. To limit exposure of specific attributes:
- In the Model Editor, select the attribute you intend to hide.
- Enable the
Do not Expose as REST
option in the Scope property.
![](/docs/assets/images/attribute-exposeAsRest-d3c9230e4a6bba286306c97c67559ee9.png)
Attributes can only be accessed via REST if their parent dataclass is also exposed. Hiding the dataclass will restrict access to all its attributes.
REST Requests
Structure
REST requests are structured to provide flexibility in accessing and manipulating data:
Base URL followed by specific parameters:
{{APIEndpoint}}/rest/{{dataClass}}
Common Operations: $filter, $attributes, $skip, $method...
Parameters
REST request parameters follow a structured format, beginning with the base URL and appending query parameters to tailor the request.
Parameters start with a ?
symbol, followed by additional parameters separated by &
:
GET {{APIEndpoint}}/rest/Person/?$filter="lastName!=Jones"&$method=entityset&$timeout=600
In the above example:
- $filter: Narrows the returned data based on specific criteria.
- $method: Determines the type of operation to be performed.
- $timeout: Sets a limit on the time the server should wait before aborting the request.
Handling Ambiguities
To avoid ambiguities, particularly with string values, it is advisable to enclose parameters in quotes. For instance, if querying a last name that includes an apostrophe, you might specify it as "lastName='O'Connor'"
to ensure the query is parsed correctly.
Data Modifications
While GET
methods are primarily used for retrieving data, POST
methods can be employed to add, update, or delete entities within a dataclass:
- POST to create new entities.
- PUT or PATCH to update existing entities.
- DELETE to remove entities.
Data Formatting
By default, REST APIs return data in JSON format. If an array format is preferred, the $asArray
parameter can be used. This is particularly useful when integrating with frontend frameworks that may expect data in a specific format.
Server Responses Codes
Each REST request is met with a server response that includes a status code indicating the result of the request—ranging from successful operations to various errors that might have occurred during the process. This feedback is vital for error handling and ensuring robust API integration:
Status Code | Type | Message | Description |
---|---|---|---|
200 | Success | Request processed without error. | |
400 | Missing API Key | Some headers are missing, required headers [api-key] | If the API key is not included, you will encounter an "Authentication Token Missing" message. |
401 | Invalid API Key | Api-key Not Valid | This response occurs when an incorrect API key is provided. |
Expired API Key | Api-key expired | If the API key has expired, the error message "Authentication Token Expired" is returned. | |
Unauthorized | No permission to read for the Users dataclass | Permissions error (check user's permissions). | |
No permission to access Dataclass | No permission to read for the Users dataclass | Permissions error (check user's permissions). | |
No permission to access Attributes | No permission to read for "Name" attribute in the Users dataclass | Permissions error (check user's permissions). | |
402 | No Session | Maximum number of sessions has been reached. | |
403 | Access Denied | 403 - Forbidden | The 403 error surfaces when the API key is valid but lacks necessary permissions. |
404 | Resource Not Found | Appid or env not found in Table. | The 404 error is shown if the endpoint URL is incorrect or the endpoint does not exist. |
Dataclass Not Exposed | The "Users" dataclass cannot be found | A 404 error occurs if the dataclass does not exist on the server or is not exposed as REST. | |
Attribute Not Exposed | The "Name" attribute cannot be found in The "Users" dataclass | If an attribute is not exposed in REST, this also results in a 404 error. | |
500 | Server Error | The 500 error indicates server-side issues; contacting the API provider is recommended. | |
502 | Request Not Processed | 502 Bad Gateway | Server might not be started. |
API Endpoint Usage Example in Postman
Setting Up Postman for API Requests
To use Postman for testing REST APIs:
Launch Postman and initiate a new API request setup.
Enter the appropriate API endpoint URL from the Qodly Cloud application.
Select the desired HTTP method (GET, POST, etc.) for your API call.
![](/docs/assets/images/postman1-696357673770f255bdab091401187a16.png)
Authenticating API Requests
Secure API requests by adding an API key:
In the Authorization tab of your request setup, select
API Key
from the Type dropdown.Enter
api-key
in the "Key" field and input your API key in the "Value" field.Ensure the API key is included in the request header for authentication.
![](/docs/assets/images/postman2-ed513a0dc968639ae2de2c4502959859.png)
This setup automatically adds the API key to each request from this configuration, minimizing manual errors and simplifying the process.