Skip to main content

Custom API endpoints

As an alternative to using the RESTful API, you can create custom API endpoints to post data to or get data from an activity on a page. This alternative is useful in situations where you cannot comply with the requirements of the RESTful API request format.

As with the RESTful API, you can use custom endpoints to allow external services to interact with your Grexx Platform application programmatically. For example, you might expose an endpoint to allow another system to place an order or retrieve details of a quote from your application.

Expose a custom endpoint​

If you have configured a page and an activity, you can expose a custom endpoint so that an external system can make GET requests for the activity data or POST requests to perform the activity.

To expose a custom API endpoint:

  1. Log in to MyGrexx and select Grexx Connect.
  2. Select the Endpoints tab and click the + icon. The Create Grexx Connect endpoint dialog is displayed.
  3. From the Server picklist, select the version of the Grexx Connect API that you want to use. Usually we recommend using the Production version.
  4. Enter a name to identify the endpoint and specify a contact email address for Grexx Support to use if needed. (Typically this is your own email address or that of someone else working on your application.)
  5. In the Path field, enter the path for the custom endpoint, beginning with /. For example, /customendpoint.
  6. From the Methods picklist, select either POST or GET.
  7. In the Allowed IPs field, specify the IP addresses that you want to allow to make requests to this endpoint. Requests from IP addresses that are not in the list will be rejected. By default, requests from allowed IPs must be authenticated.
    • To allow requests from allowed IP addresses without authentication, enable Allow anonymous.
    • To allow requests to be made from any IP address, enter 0.0.0.0/0.
  8. From the To environment picklist, select the application DTAP environment on which you want to expose the endpoint.
  9. In the To page field, enter the case ID (from your Studio) of the page containing the activity you want to use. To view the case ID of a page casetype, open the Casetypes list, select Columns, and enable the ID column.
  10. In the To activity field, enter the case ID (from your Studio) of the activity that you want to post data to or get data from. To view the case ID of an activity, open the Activities list, select Columns, and enable the ID column.
  11. Click Submit. The endpoint is created.

To view the full URL for the endpoint, click the "information" icon.

Unless you have allowed anonymous access, you need to configure authentication for the endpoint. You can either use basic authentication (and require a username and password each time a request is made) or token-based authentication using OAuth 2.0.

Configure basic authentication​

To use basic authentication and authorization, create one or more Grexx Connect service user accounts and grant them rights to the endpoint:

  1. From the Grexx Connect page in MyGrexx, select the User accounts tab.
  2. Click the + icon. The Create Grexx Connect user account dialog is displayed.
  3. From the Server picklist, select the version of the Grexx Connect API that you want to use. This should be the same as the server used for the custom endpoint.
  4. Enter a name to identify the user account and specify a contact email address for Grexx Support to use if needed.
  5. In the Username field, enter a username for the user account. The username must be unique throughout Grexx Connect.
  6. From the Type picklist, select Service.
  7. In the Allowed IPs field, specify the IP addresses from which this user account may authenticate. To allow requests to be made from any IP address, enter 0.0.0.0/0.
  8. Click Submit. The user account is created.
  9. Select the Endpoints tab and click the "add user" icon.
  10. Select the user account(s) that you want to allow to make requests to the custom endpoint and then click Submit.

Once you have configured the endpoint and user account, click the "information" icon to view the full URL for the endpoint and the permitted users. You can paste the URL into your browser or use an API test tool to test whether you can make requests and that the authentication works as expected.