Start integrating with ONEiO for free!
SIGN UP

Endpoint Type Configuration Guide - Custom REST

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.

 

Snip20200626_16.png

 

 

  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.

mceclip4.png

I've also set JSON to be my inbound content type and the element where ONEiO resolves the entity type be entity_type.

mceclip1.png

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.

mceclip2.png

Then add a simple json as a payload and send the request.

mceclip3.png

If everything went ok, you should receive a transaction id as a response.

You should now see the message in your feed.

mceclip5.png

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:

mceclip0.png

And your Postman call would look like this:

mceclip1.png

And the message in the feed

mceclip2.png

 

 

  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. 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.