Welcome to the Sabueso REST APIs
Introduction to the structure of The Sabueso REST APIs
You're on your way to building an awesome developer hub! Here's some of the things you'll want to check out.
LEARN THE BASIC CONCEPTS USED IN OUR PLATFORM
Our APIs are based on a pattern that retrieving resources with providing notifications that indicate the status for the petition. The HoundExpress REST APIs use a json object that could be POSTed to us and have a standard structure where you must send to a specific target.
Therefore it is necessary you to know the endpoint service you want to use. You can consult it in the section of each service.
RETRIEVING RESOURCES
The body request defined for the consumption of our APIs is a json object having a structure almost common for all our deployed services.
COMMON PARAMETERS WITHIN THE HEADER
For the consumption of any of this APIs is necessary that in the header of the request a series of parameters required for authentication be included, since they are part of the mechanisms incorporated into the security environment.
| Parameter | Description |
|---|---|
| idClient | This field specifies the identifier assigned to your company partner of The HoundExpress. This value must be requested from a user of your company who has a MainPartner profile, and can only validate at the moment of the implementation in a productive environment. |
| partnerKey | Is the key assigned by our system at the moment of your registration, and is part of the authentication mechanism that our system implements. Remember, in case of you change your password, the system will assign you a new Partner Key, so you need to be careful to keep your systems synchronized. |
RESPONSE TYPES
When a request is made to an API in which we consult some resource, the answer can be of two types:
The required information to be received within a json object.
In this cases, the response for your request lets you know if the request was made successfully or rejected by an array of errors. If this array is empty it means there are not errors detected in the validations incorporated within the HoundExpress REST API.
Otherwise the array will contain the list of errors that must correct previously in your application to make a successful use of The HoundExpress REST API services. We suggest you to implement a validation of this array in your development.
In case of formats like images, documents, PDF, etc., it is possible to receive a response with the stream file.
However your application shall be able to handle next errors defined by IETF RFC 6750.
| HTTP Status | Error code | Description |
|---|---|---|
| 400 | invalid_request | The Web API request is missing a required parameter, or includes an invalid or malformed parameter value. This error is returned in an HTTP 400 Bad Request error response. |
| 401 | invalid_token | The Web API request contains an expired, revoked or invalid access token. This error is returned in an HTTP 401 Unauthorized error response. Additional information about the error MAY be provided in the WWW-Authenticate header |
| 403 | insufficient_scope | The Web API request requires higher privileges than provided by the access token. This error is returned in an HTTP 403 Forbidden. |
| 500 | Server Error | The Web API cannot be processed due to a runtime error |
| 503 | Service Unavailable | The Web API cannot be processed because the service is unavailable |
SECURITY
Basic security elements used in The Sabueso REST API
Tokens
For The HoundExpress REST APIs platform there are two kinds of token:
| Type token | Description |
|---|---|
| partnerKey | It’s the key token assigned by our system to users with develpRole, at the time of registration, is part of the authentication mechanism Is directly related to your password, so we beg you to pay particular attention If you change your password, because the system will assign you a new partnerKey. And you must do the adjustments to keep your systems synchronized. |
| temporalKey | Access token with limited time (credential) used to Access API web of The HoundExpress REST APIs, implemented with this mechanism. Usually it's only required for special or custom web services out of the standard APIs, don't worry if you doesn't have one at this moment |
This tokens are used for validate that the request comes from a verified system.
ROLE
There are different roles for the consumption of APIs, designed with the purpose of providing differentiated privileges to each of the registered users.
| Type role | Description |
|---|---|
| DevelopRole | This role is related with a user profile on development process under the platform The HoundExpress REST APIs, has privileges under a testing environment that allows him to perform his development. This role is assigned as prior to validation by HoundExpress and is exclusive to develop your system. This role couldn't be used to operate |
| ProductionRole | Once a developRole user has finish the development for the consumption of services under The HoundExpress REST APIs platform, requires the validation from the Hound Express IT area. If no problems are detected, the user can obtain this role that will allow operate under the productive environment of the services. From this moment, real operative processes are generated and triggered. |
Therefore the final step is when you get the validation and the ProductionRole
Another considerations about The HoundExpress API Limitations
DEFAULT NUMBER OF REQUEST PER MINUTE
Your application should limit access to under 300 times in a 60 seconds period, with no more than 50 concurrent requests in any time. The HoundExpress API will throttle your requests when this limit is exceeded.
If your application and security requirements needs a different setting, please indicate your requirements during your application registration.
Updated about 1 year ago