API Introduction
The iPaaS.com API helps subscribers manage your iPaaS.com subscription and mappings configurations as well as CRUD (create, read, update, delete) data operations; Integrators can manage their private and certified integrations; and Managed integration Service Providers (MiSPs) can automate subscriber account relationships.
All CRUD endpoints in the API follow REST conventions and use standard HTTP methods. Different URL endpoints represent different data models.
You can find a list of our swagger pages here.
Getting Started
iPaaS.com is API first, meaning that anything you can do in the platform you can do by making an API call. The database sits behind the API and is accessed through it. In addition, the UI is entirely driven by the API so any actions you take there are executed via the API.
Permissioning in iPaaS.com is role-based and also handled via the API. You can use either your username and password or a token to authenticate. If a role or user is updated the token will need to be regenerated.
Authentications
Access to iPaaS.com APIs can be obtained by user credentials or an API Key.
User Credentials
Because users of the iPaaS.com platform will perform operations across many companies, authorizations are maintained by the company and not the user.
When accessing iPaaS.com, users will initially authenticate themselves as a user and then retrieve authorizations by choosing a specific company to work on behalf of.
An access token will be provided for that user/company session, which will then be used for authorizing all future requests within any iPaaS.com API until it expires.
Please use the iPaaS.com SSO API to perform User Authentication and retrieval of an Authorization token.
Perform User Authentication at /v2/Auth/Login by providing username and password. A successful response will return an access_token which will be used to perform the next two steps.
Optional (If you already know the company_id, you may skip this step): Identify a List of Company Ids this user is affiliated with at /v2/User/{id}/Companies. Otherwise, select the company_id for the company you wish to login as and proceed.
Retrieve Authorizations by providing the company_id and a user access_token at /v2/User/ChangeCompany/{id}. A successful response will return an updated access token that contains authorizations for that company.
This is covered in more detail here.
API Key
If a company has issued an API Key to access their settings and/or data on their behalf, the API Key is already configured as a company access_token containing all approved authorizations by that company. You can see how to create one here.
Authorization
Once you have retrieved a valid access token, you can access any authorized API end-point across all iPaaS.com APIs.
To do this, add a header with key “Authorization” having a value of your access_token
Example Curl
curl -X 'GET' \ 'https://api.ipaas.com/subscriptions/v2/Events?pageNumber=1&pageSize=100' \
-H 'accept: text/plain' \
-H 'Authorization: {access_token}'
See how this is done in the Swagger UI here.
Error Handling
Status codes overview:
Code | Message | Overview |
200 | OK | A request was accepted and handled successfully. |
201 | Created | A new resource was created successfully. |
400 | Bad Request | This includes:
|
401 | Unauthorized | No authorization, or incorrect authorization was provided for the resource.
This could mean:
|
404 | Not found | The requested resource does not exist or cannot be found by the URL. |
429 | Too many requests | Too many sequential or concurrent requests to a specific resource or endpoint were made. |
5xx | Server error | iPaaS.com was unable to serve the request due to an internal failure. |
Any other error codes not explicitly defined above are not defined by iPaaS.com and may be the result of a client or server setting.
Response payloads
Responses will generally include the data requested, modified, or created. A PUT or POST call will receive a response including the full updated entry.
For errors, the error message will be returned as the body in plaintext.
Rate Limits
Users may occasionally see 429 errors, indicating too many requests. While rare, users may have a defined amount of API calls per month as part of their billing plan. When permitted by the details of the billing plan, exceeding the allowed calls will result in an overage charge rather than strict cutoff of API calls. However, if the billing plan is not set up to allow overage charges, any API calls beyond the monthly allowed range will return 429 Too Many Calls errors.
Regardless of the allowed amount of API calls, users may also see a 429 error if certain databases or other resources are overwhelmed by the user’s current call volume. The error message in the response body will indicate if the error was due to monthly limits or to temporary volume restrictions.
Pagination
Pagination data in the API is returned in the X-Pagination header as a JSON object. For example:
{"total_Count":165,"page_Size":100,"current_Page":1,"total_Pages":2,"previous_Page":"No","next_Page":"Yes"}
This metadata includes:
total_Count: The total number of records available
page_Size: The size of each page
current_Page: The current page number
total_Pages: The total number of pages
previous_Page: Flags indicating whether there is a previous page
next_Page: Flags indicating whether there is a next page
Versioning
iPaaS.com is currently on V2 of our API, but is quickly moving to launch V3. As an integration platform, we want to make sure our API changes require minimal, if any, changes when they are upgraded as to not break the integrations built on the platform. When V3 launches, it will be backwards compatible with V2. At this time we do not expect to launch any API versions or endpoints that are not backwards compatible.