API Gateway | Setup

Setup

To set up an OData endpoint that you can connect to, you will need to first request an API enabled EBMS Relay Key from Eagle Business Software. This will allow access to your data securely from anywhere in the world.  There is a $50/month fee that includes both the API enabled relay key and EBMS API support.

Note: if you have your own SSL certificate and domain name, you can set that up on your EBMS server using port 23200. If you do go the route of using a direct connection instead of using the EBMS relay, you may need to work with your IT department to make sure that the API is not blocked by your firewall. In this scenario, you should still follow points 5 and 6 below; your URL will be
https://[your domain]:23200/MyEBMS/[your ebms data id]/Odata/]

Once you have received that relay key from Eagle Business Software, follow these steps to configure your server:

1. 1. Open the EBMS Server Manager on your EBMS server
2. 2. Click Settings and then go to the Advanced tab
3. 3. Enter the EBMS Relay Key into the field marked Relay key
4. 4. Close settings to return to the main EBMS Server Manager screen
5. 5. Find the company whose data you want to access and turn on Enable external services
6. 6. When prompted, press Restart EBMS services. This may take a minute or so to take effect

Your OData endpoint should now be open! To verify that the endpoint is running, you'll need to note your EBMS serial number and the three-character ID of the data that you want to access.
Once you have that, enter this url into your browser:
https://ecc[your serial number].servicebus.windows.net/MyEBMS/[your ebms data id]/Odata/
This should display a list of entities that you have access to in an XML format. You do not need any credentials to view this metadata.

Using the service

We recommend that you use either Postman or LINQPad for testing your API requests. These tools provide an easy-to-use interface to help you see what is happening and diagnose potential issues. Of course, eventually you will be making the calls using your application or API but we recommend that you use the tools while you explore and test your use of the API.

Once you have one of these tools, let's do a demo query to get a single customer record

1. Open Postman (or another tool, we'll use Postman for this example) and enter your URL (see the url format above) but add /ARCUST to the end
2. To find a specific customer, add this to the end of your URL: ?$filter=ID eq '[some customer id from your data]'. Your url should look something like this:
   https://ecc123456789012345.servicebus.windows.net/MyEbms/ABC/Odata/ARCUST?$filter=ID eq 'TESTCUST'
3. Make sure that the method is set to GET
4. Set the Authorization to Basic Auth and use a valid EBMS username and password. Since this is transferred over https, your password will remain encrypted during transport.
5. Press send!

If you are consuming this service using .NET there are a few Microsoft libraries to make things easier for you:

1. OData Connected Service
2. Microsoft OData Client

Things to know

1. Requests to the server (excluding metadata requests) always require authorization. You can do this by adding a Basic Authentication authorization header using an EBMS login.
   "Authorization", "Basic [Username]:[Password]
   Example:
   "Authorization", "Basic MyUsername:myPassword"
2. Entities marked as "Virtual" are not stored in the database and cannot be queried
3. Properties marked as "Virtual" are not stored in the database and can be read and written to but cannot be used in a query
4. References between tables are stored in the database as natural keys (or, in some cases, AUTOIDs which are similar to GUIDs). However, there are "Reference" properties that are computed to create actual associations between the tables. These are named as [PROPERTYNAME]_Reference. For example, ARINV.CUST_ID is the invoice's customer id; ARINV.CUST_ID_Reference is an actual reference to the customer (ARCUST) itself. You can read/write either the natural key property or the reference property. Another example expands and returns information from an entity's detail table. e.g. https://ECC123456789012345.servicebus.windows.net/myebms/ABC/OData/ARCUST?$filter=ID eq 'DOEJOH'&$select=Title&$expand=ARCONTACTSs($select=Title,Subtitle,EMAIL,B_PHONE) returns a list/collection contacts for a customer (CRM module required). Properties are case sensitve.
5. All EBMS entities are inherited from the EbmsEntity entity
6. Many entities are additionally inherited from EbmsDetailEntity entity. These entities are "child" or "detail" entities such as invoice details, customer contacts, etc. They are lists within another entity and must be accessed through their parent. See these examples to see how to edit entities, especially child entities.
7. It's strongly recommended to select precisely the properties that you need when running a GET because returning all properties will take significantly more time to fetch the data.
8. A list of properties per entity can be found by using the EntityMetaData endpoint.  e.g. https://ECC123456789012345.servicebus.windows.net/MyEbms/ABC/OData/EntityMetaData('ARCUST')?$expand=Properties
9. Multi-level queries are not supported in the EBMS API
   e.g. https://ecc123456789012345.servicebus.windows.net/MyEbms/ABC/OData/ARCUST?$filter=ARCONTACTSs/any(s:s/B_PHONE eq '(800) 421-0771')
10. If you are using your own domain and SSL certificate make sure to set up the Eagle website with a binding to port 23200 using your SSL certificate
11. When you post data to the server, make sure to mark the request as JSON content

What you can do?

1. Supported methods in the API are GET (query and return data), PATCH (edit existing entities), POST (create new entities), and DELETE
2. Click here to see a list of entities and properties that are exposed to the API
3. Click here to see some examples of what you can do with the API