Endpoint details
In this document, you will find detailed info about Custom REST Endpoint Type. This Endpoint Type is a Self-Service type, so users can add them without a need to reach out to ONEiO Support.
This endpoint type contains a narrowed-down set of functionalities. Note that this limitation applies to self-service only. You can reach out to ONEiO Support in case you need to build more customizations around authentication methods, attachments, etc.
| General | |
|---|---|
| Status | Sets the status of the endpoint. Active / Suspended |
| Name | Name of the endpoint. It is recommended to use short names since this name is used in displays throughout ONEiO. |
| Your REST API base URL | The base address of your REST API. You can test the HTTP connection by clicking the "Test Connection" button. Note that this function does not test the authentication, only if ONEiO can reach the endpoint. |
| Username | The integration user that is used in all calls to your REST API. These include updates and lookups. The authentication method used is HTTP Basic. |
| Password | The password to the integration user. |
| Timezone | The timezone used in your REST API messages. Note that this is used only if your DateTime pattern does not include the timezone information. |
| Datetime pattern |
Date time pattern ONEiO uses to read DateTime fields and how ONEiO sends out DateTime fields. The valid pattern is according to the Joda time format. Additionally, the value of EpochTime or EpochTime_s can be used when the inbound date-time is in milliseconds or seconds since Epoch. |
| [Your REST call] -> ONEiO | |
|---|---|
| Receiver address |
The address to send your REST call is the following.
The targets are different when operating in QA or Production.
|
| Username | Username (and password) to be used in your REST call. The credentials are to be used with HTTP Basic authentication. You can reset/retrieve a password in edit mode. |
| Inbound Content-type | Decides the content that is read in the inbound message. Possible values JSON or XML |
| Entity type element (only with JSON) | The element in the inbound message tells what entity type the message is. (See examples for more details) |
| Inbound Attachments | |
| Method | Decides how ONEiO reads the incoming attachments. They can be either inlined in the actual message as base64, or the message can contain a link where ONEiO downloads the file. |
| Attachments element | The container element contains all incoming attachments. |
| Attachment element | If the container has a separate element for all attachments, this element name is set here. If not, this should be left empty. |
| Attachment content-type | The element that contains attachments content type. |
| Attachment filename | The element that contains the attachments filename |
| Attachment data | The element that contains attachments data as base64 |
| Attachment download URI | If you select method Download, this describes the URI where the file is downloaded from. You can use a fixed URI or a placeholder or a combination of those. |
How to test?
You can easily test your inbound configuration with a tool like Postman. Just simply create a request, use the credentials from your endpoint.
In this example, there are two entity types; cat and dog.
I've also set JSON to be my inbound content type and the element where ONEiO resolves the entity type be entity_type.
First, create a new request. Do a POST to https://rest-receiver-test.service-flow.com/api with basic auth credentials from the endpoint. Username is on the screen and password I can get by clicking Generate new password.
Then add a simple json as a payload and send the request.
If everything went ok, you should receive a transaction id as a response.
You should now see the message in your feed.
You can also test with XML. In this case the entity type is resolved from the root element of the XML.
Endpoint configuration would look like this:
And your Postman call would look like this:
And the message in the feed
| ONEiO -> [Your REST API] | |
|---|---|
| Outbound Content-type | Decides the content that is used in the outbound message. Possible values JSON or XML |
| Outbound Response Content-type | Tells to ONEiO the content type that the API will use in the sync response. |
| HTTP method of Create | HTTP method used with CREATE messages. This means the very first message towards this endpoint of a certain id. (e.g. start of a new conversation) |
| Target for CREATE | Resource used with CREATE messages. This means the very first message towards this endpoint of a certain id. The used in the call URI will be the combination of the base URL of the endpoint and this value. |
| HTTP method for Update | HTTP method used with UPDATE messages. This means all the next messages towards this endpoint of a certain id. |
| Target for UPDATE | Resource method used with UPDATE messages. This means all the next messages towards this endpoint of a certain id. The used in the call URI will be the combination of the base URL of the endpoint and this value. |
| Unrecoverable HTTP error codes |
List of numeric HTTP response codes that are to be handled as non-recoverable when sending messages to your REST API. If ONEiO receives an error code that is not on the list, it will retry the message automatically. If ONEiO receives an error code that IS on this list, the message will result in an error. Values are separated by a comma. |
| Outbound Attachments |
|
| Method |
Decides how ONEiO handles the outgoing attachments. At the moment, they can be only inlined in the actual message as base64. The possibility to upload the attachment separately will be introduced soon. Note that this limitation applies for self-service only. You can reach out to ONEiO Support in case you need to build more customisations around attachments. |
| Attachments element |
The container element that contains all outgoing attachments. |
| Attachment element |
If the container needs to have a separate element for all attachments, this element name is set here. This is only applicable with XML. |
| Attachment content-type |
Element that contains attachments content type. |
| Attachment filename |
Element that contains attachments file name |
| Attachment data |
Element that contains attachments data as base64 |
Entity types
You are free to create the entity types you need with Custom REST endpoint type. In entity type, you can also override the outbound properties that you have set in the General tab.
Comments
Please sign in to leave a comment.