REST Overview Novel


(Bart Elia) #1

My apologies if you are confused about the REST services so let me try to fix that by giving you a fly over. It’s pretty long and many Geek areas dropped into. If you want something written for normal human being and not geeks, please check out the documentation in the online help. I spent significant time having geek to normal translation done.

The new REST ‘wrappers’ have all the features of the existing web services. GetByID, GetRows, GetList, Update and all those custom methods on every service are all there with full abilities.

The difference is a different technology than the WCF endpoints where people are used to going into Visual Studio and clicking on ‘Add Web Reference’ and sucking in SOAP. That’s all still there, has full love and still worked on – evidence is all the new bindings people see lighting up all over for the various HTTP bindings including full F5 support. Nothing removed. Instead this is a recognition that one size does not fit all.

So why the heck did you add these?
The reality of technology today is everyone wants to unlock their data and get it where they want it. If you can only put functionality on a green screen in front of people today, a large majority wouldn’t be happy. They need their data in a browser remote anywhere, a phone, in Excel or some data analytics tool Epicor has never heard of. Also, you don’t want to pay a gazillion dollars to us for the client tool. In fact, most don’t want a tool at all. They want to point Excel at some Epicor server and get data without installing anything. If some JavaScript guru in your company wants to throw together some cool form for a browser mashup for their group or a little phone app, they don’t want a rigid path to freeing the data from an Epicor Server. Also, this whole Internet of Things and sensors all over the place don’t always have a full version of Windows running on them needed to push data into Epicor. All these use cases come back to needing a simple means to access / submit data in Enterprise Systems that SOAP promised long ago by bridging the gaps between competing technologies. That where the new REST services come in…

REST at its core is simply a URL. You call www.bing.com and you get back an html page and some pretty pictures in a format to show in a browser. You call http://www.bing.com/search?q=Epicor and you get back an html page about Epicor. You just did a ‘SQL Query’ of sorts but using a URL. We have done the same thing for all the ERP 10 services.

You want to get records from the SalesOrder service? Once REST is enabled in Admin Console and IIS, pop this into your browser:
https://YourServer/YourShare/api/v1/Erp.BO.SalesOrderSvc/SalesOrders
You get a login prompt for your Epicor credentials (e.g. – manager / manager).
Ok that and voila you get back a ‘GetRows’ of a bunch of data in some goofy format no human wants to read. (Ok, I like reading it but I’m a geek not a normal human being…)

Wait, what’s this goofy data, where is my where clause, I thought going at the database with a query by passes calculations and security! how the heck am I supposed to find anything…
First, the security aspect. Even though this is similar to querying a table (or tables) in the database, this is actually querying the public services we have been using for years. If you have column filtering, a calculation in a BPM or anything else, that all appears in the REST endpoints – even your UD fields.
Next, let’s pull apart that URL to start trying to understand how this is put together.
https://YourServer/YourShare/api/v1/Erp.BO.SalesOrderSvc/SalesOrders

https://YourServer/YourShare
The root is the same as you are used to pointing at. It’s wherever your IIS server is serving up the server or wherever the SaaS Ops team told you to select during install.

/api
Wait, what’s that? Usually there is ERP for the product, ICE for the system?
Well that’s the new home for all the REST toys we are talking about.

/v1
This is our new versioning mechanism. We recognize we will have to change this technology someday. That’s technology. I still miss my VT100 against a VAX but it’s hard to fit that in my Android phone. Things change so we assume at some point we will have to as well. When we do improve things and version, we need to preserve the current signatures so integrations you do from your IoT Refrigerator into ERP keep running.

/Erp.BO.SalesOrderSvc
Ok, something that finally looks somewhat familiar. Under the ERP / BO folder there is a file named SalesOrder.svc, right?
Yup gold star. We use the same organization in REST as you have been doing in v10 for some time.

/SalesOrders
SalesOrders. I already said SalesOrders so why am I repeating myself??
Well you drilled down into the SalesOrder Service but now you need to ask for what you want once you got there. OrderDel? OrderRel? In this case we asked for SalesOrders. These are all ‘Resources’ of the Service.
Another example might be:
<…>/FordSvc/F150
Ford provides an F150. SalesOrderSvc provides Sales Orders.

Now let’s get back to that goofy return value. What’s with that??
The format is called json (pronounced Jason). It’s extremely terse. No pretty xml element names to give you a hint about what it is. All that knowledge is kept outside the payload and you have to ask for help instead of having it forced on you when asking for data. That makes this format very small and perfect for going across the internet and slow cell phone networks. It’s also the native format in JavaScript to light up on a web page in a browser or on a phone. Those technologies no longer have to parse through a large slug of data returned to show on the screen. Got json? Slap to screen, done.

But I like my xml for interop? It’s self-describing!
Where was the where clause? I need to search on the customer!
Where am I going to find anything about any of this? Do I have to read some huge dev doc??
Let’s sneak up on all these by first not ignoring all the doc effort put into the standard docs. We have some excellent info on this in the online help so please browse over to your help site and drill down into System Management -> Working with System Management for the REST Implementation section. This has all the setup and background that you would need and some good examples.

But if you are like me… who reads the manual?
Instead let’s look back at the URL again
https://YourServer/YourShare/api /v1/Erp.BO.SalesOrderSvc/SalesOrders
Remember I said api had all the toys here? What about help?
https://YourServer/YourShare/api/help

The REST services are their own documentation. Want to see what services are available? Click on the Service List and search for the one you are interested in. (Yea, we have something like 1600 services so added a search box there for you, try it out).

Also if you have spent a week building up that perfect shape of data in a BAQ, have no fear, it’s there. Start typing its name and you’ll see it appear to select it.

Once you find your service or BAQ of interest then you move onto the help page for that resource. Let’s look at SalesOrderSvc for a reference-

Whoa, swagger? GET / POST / DELETE / PATCH?
Let’s get some background. Swagger is a formatting standard to doc REST services. It’s one of the gazillion bouncing around these days with all the cool kids doing internet enabling refrigerators and IoT devices monitoring their dogs eating habits. Luckily it is actually really nicely done and helpful as heck. So we decided to leverage it. Microsoft Azure did also so we feel pretty good about using the same approach.
Get / Post / Delete / Patch is the http version of the Epicor core methods of GetRows, GetByID, Update, Delete, etc. These are standard verbs for HTTP and allows the Epicor REST services to play nice with other internet technologies. It makes getting the data in and out of ERP 10 easier with a variety of modern internet tools. This is not to say we don’t have the Core methods anymore though! If you look at the top of the page you will see ‘Custom Methods’. This flips the docs over to look at the entire list of service methods you are used to seeing in a client customization or in Visual Studio Add web reference:

Let’s go back to the oData list and take a look at the $metadata resource. This is a standard ‘method’ on all services that list all the resources available for the service and the shape of the data going in and out of the service:


This is kind of a combination of a database ERD and an API reference all in one. It lets you know what is needed or available and a start to providing much richer documentation.
Now let’s drill into that original SalesOrder resource:

There are a couple of sections here. The upper section is the Model and Model Schema. The Model Schema is the shape of the data and some sample data as shown above.
The Model itself has a ton of information on the actual table and its columns:

And this Resource has a few parameters it can recieve to start doing a ‘where clause’ of sorts.

These parameters and a bunch more are part of an open standard called oData (www.oData.org). A bunch of tools speak this language already – Excel, PowerBI, Tableau, LINQPad, probably a few dozens more I have no clue about. They send the ‘SQL Queries’ / ‘Where clauses’ in this format. You can leverage the tools and point them at the REST service or go learn the language at oData org, it’s YOUR CHOICE.
Let’s try a couple of simple examples.
First, that json format is great for browsers but rough on integrations. To get the xml you are used to seeing you need to simply ask for it:
https://localhost/erp10/api/v1/Erp.Bo.SalesOrderSvc/SalesOrders/?$format=atom

We are starting to dig into the syntax of the ‘query string’. We start with a ‘?’ to tell the server I have a request on that resource. Then you tell it to give it to you in ‘atom’ format. This is a web standard for xml (https://en.wikipedia.org/wiki/Atom_(standard)). If anyone remembers RSS newsfeeds, this is an enhanced version and plays great with data analytics tools like Excel and PowerBI.
What this means is as a consumer of the REST services, you can ask the server how you want the data shaped. You don’t have to do that in your client. We are trying to allow for flexibility in what you want and not force you to do the shaping of the data in the client.
Next, let’s think about how a normal flow in using a form. You go to the form –

  • Open Sales Order
  • Search and get a list of Sales Orders - Sales Order service - GetList is called
  • Select one (or more) Sales Order service – GetById (or GetRows) is called
  • Make a change and save Sales Order service – Update is called

Obviously grossly simplified but this is an intro :wink:
In the REST world, we are using standard HTTP verbs. GET is the verb for any query. Just like we had to ask for xml, you need to ask for one or more and in what shape explicitly. GetList is similar to a view in SQL server. No child tables, just an extremely lightweight and fast way to query against a flattened version of a resource – Sales Order in this case. You see that in the Search forms normally. It’s not perfectly in alignment with the internet religion but does provide a helper for those used to the List / Full pattern of querying in ERP10 / E9 / Vantage 8 / E4SE / Clientele. In REST we provided a simplified version of this through the ‘List’ resource –
https://localhost/erp10/api/v1/Erp.BO.SalesOrderSvc/List

Note the first three records for ‘query’. Let’s note the first one and do a ‘GetByID’. SalesOrder as a resource has two primary keys to identify itself. A Company and an OrderNumber. The help doc highlights this for us and gives a hint on the syntax for the ‘SQL where clause’:

Note how the Company and OrderNum fields are prompting you to enter the primary keys. Let’s grab that first record retrieved in the List and ‘try it out’:

There is the record in the Response Body. Note the ‘Request URL’ builds the ‘query’ for you. Let’s try that in a browser:

We are starting to see the syntax in querying that ERP10 supports. It’s an open standard named oData (www.oData.org). Let’s pull it apart a moment.

/SalesOrder(Epic06,5000)
‘SalesOrder’ is the resource as previously stated. If you used OrderRels it would have queried against that table instead.

(Epic06,5000) is the where clause. Note above the help doc said Company and OrderNum were required. oData uses that requirement to infer the column values being passed and which is which based upon the order they were displayed in the metadata above. If you want to be verbose you could state /SalesOrders(company=Epic06,OrderNum=5000). Both are supported, again the philosophy of doing what is asked of the client or integration.
So we can query in a fast lightweight fashion like a GetList. We can do a GetByID.

What about retrieving multiple rows like GetRows? Time to drop into more oData syntax and try out the filter command:


This builds out the URL:

Or in a browser address as ->
https://localhost/erp10/api/v1/Erp.BO.SalesOrderSvc/SalesOrders?filter=Company eq ‘Epic06’

What is ‘eq’?
What’s with the goofy % things in the URL?
We are looking at a lot of columns in these tables making it hard to understand!
First let’s pull apart the query – ‘eq’?
Since this is an HTTP URL you have to follow all internet standards in making an address. ‘>’, ‘<’, ‘=’, ‘!=’ etc all mess up a normal URL. Instead of these oData has replacements:
Equals eq
Not Equals ne
Greater Than gt
Greater Than or Equal ge
Less Than lt
Less Than or Equal le
And and
Or or
Not Not

Spend some time in the oData examples if you need to learn the new syntax.
Next is the padding in the URL. This is URL Encoding (https://en.wikipedia.org/wiki/Percent-encoding). It’s a mechanism to not mess up URL parsing by using a ‘%20’ instead of a space for example. Most browsers automagically change spaces to %20 for you for example. It’s a simple translatioin.
Lastly, there are some extremely verbose tables in many Enterprise systems. One of my favorite parts of oData is being able to specify just the columns I care about.

Maybe we only want to see the open order status and the customer number?

https://localhost/erp10/api/v1/Erp.BO.SalesOrderSvc/SalesOrders?%24select=Company%2COrderNum%2COpenOrder%2CCustNum&%24filter=Company%20eq%20'Epic06'

Wow, just the data you want almost like a BAQ?
Pretty much. Without having to persist a new query to the server or ask IT for a new service you can tell the server through REST what data and how to shape it.
Not too many people are going to want to live their days in a browser to query the database though so let’s look at the world’s most popular querying client – Excel. You’ll need to refer to the docs for the appropriate version of when you need to download the oData addin from Microsoft but in the 2016 version it’s already baked in:

Let’s point at the SalesOrder service again with our ERP 10 user credentials:

And select the table you want to show

And you have a live link to the data behind the services with just client tool provided open standards. Nothing Epicor or Microsoft or anyone owns, just everyone agreeing to use an open standard.

The really nice thing about this under the covers is that Excel is speaking oData. Sorting, limiting columns, filtering of a column in the table all send across queries in oData syntax. This means you don’t dump the entire data base across the network and into Excel.
PowerBI, Tableau and anything speaking oData does the same thing.

Great for a readonly view of the world but what about Updating ERP 10?
All the URLs shown so far are simply reading data out of the system. An HTTP GET. GETS’s can be executed as a browser URL address and the response is shown in the browser client. Updating data uses the other HTTP verbs which need a tool or code to execute
POST – Does an Insert
PATCH – Does an Update
DELETE – Does a Delete
Underneath the covers the normal Update method is followed with validations, BPM intercepts, etc. There are code examples in the online help so based on your comfort zone learn what URL helpers play nice in your language and platform. They all have them. C#, VB, JavaScript, Python, PHP, Windows, Linux, it doesn’t matter. They always have an HTTP stack so can access ERP 10 directly now.

So take it for a tour, please ask questions. I am curious about what we did NOT think about.


REST API - How To? and Where
"Best" way to export data on a schedule
REST command line
How can I see what business objects and methods are being called on an action and how do I use them?
Can a BAQ access the data from the User Tracker?
How can I track concurrent active users?
Copy to Excel
REST interface header key-value pairs
User Credentials Lookup
E10 in Visual Studio 2013
SOAP webservices changing / phasing out?
UI Processes
(Kenneth Hayes) #2

SOOOO excited to get my hands on .500 and try these out!

Thanks for sharing Bart!

[Ergobaby Logo]

Kenneth A. Hayes
Director, IT | Ergobaby
Find us: ergobaby.comhttp://www.ergobaby.com | facebookhttp://www.facebook.com/ergobaby/ | instagramhttp://www.instagram.com/ergobaby | pinteresthttp://www.pinterest.com/ergobaby | twitterhttp://www.twitter.com/ergobaby | youtubehttp://www.youtube.com/ergobaby


(Bart Elia) #3

It’s obviously for customers but I hope to energize lots of partners with this tech. Tell me what you come up with for the ecosystem!


(Rob Bucek) #4

Epic read, and very exciting! Thanks for sharing!


(Bart Elia) #5

Had nothing to do on the flight :wink:


(Jose C Gomez) #6

(Jose C Gomez) #7

I pinned this since it will be very useful once 500 is released to the messes. Thanks @Bart_Elia


(Chris Conn) #8

This is all very exciting stuff - and so much content, thanks for your effort in putting this together (not to mention the actual hard work of making it happen). Now that I buttered you up, some stupid questions:
What version does this become available on? Is it already available?
How much configuration is involved in enabling these services?

I am certain my IT team will never in a million years touch this with a stick but I sure would love to play with it. My organization is really strange - literally my IT department manager rarely responds to my calls or emails, despite Epicor being such a big priority, with me right smack in the middle of it.

Would be nice if there was a way to setup my own test environment, on a device I control so I could wave some of these fancy solutions around in their face after the fact. That said - is there a such thing as a test setup I can get access to? I have had no exposure so far to the setup and configuration of an environment. If in fact, I do have access to such a beast, is there an Epicor setup guide for dummies?


(Jose C Gomez) #9

This comes out in 10.1.500 out “soon” (it’s out in beta and deployed to the epicor cloud already)

Configuration is a checkbooks or two in the admin console

You can setup your own environment get you an install guide and an epic web account. (Your employer can give you access) and go to town

There are all the user guides and install guides


(Chris Conn) #10

Great found it. Now if only I had a Windows Server machine :blush: Despite all of my fancy SSDs and massive pool of RAM, I don’t have the right OS. Are those requirements actual REQUIREMENTS or just really strong suggestions? (For the sake of playing)

Btw, how do you guys get those super cool title badges? I need one that labels me as “Thread Hijacker”


(Jose C Gomez) #11

Ask and you shall receive… (Title)
Also get virtual box and install win server on it :smirk:


(Bart Elia) #12

Butter up not needed. This group seems to have a lot of tinkerers and people pulling things apart. Also some outside the box thinking orgs/partners. It’s marked tech preview because we want feedback. I am on another project now looking way forward but this tech or something similar is needed for it. I’d prefer to build coherent and iterative solutions everyone including myself can count on :wink:

It is in 10.1.500 and live on SaaS.
Review the docs as mentioned in the overview. It’s basically two steps
-Check the box in admin console to enable the settings in web.config
-Setup SSL in IIS
NOTE - We added documentation for using Self-Signed Certificates for SSL / HTTPS for those not willing to pick up an SSL in IIS book and try things out for free :wink:

The question on reducing barrier of entry on getting things setup is a hot topic internally with a lot of great ideas bouncing around. Stay tuned and I hope by next Insights we will have some roadmap to share.


(Joshua Giese) #13

If you want a group of rule breakers you came to the right place LOL you have a couple rogues in here that find new ways to make Epicor bend to their will that make Nathan cringe lol

Joshua Giese
CTO
920.437.6400 x342
Wisconsin Converting Inc.


(Rob Bucek) #14

I’m innocent, I swear it


(Jose C Gomez) #15

Let’s Encrypt for the win!!!
https://letsencrypt.org/

I used it for my 500 REST setup works like a top no self signed needed :grin:


(Bart Elia) #16

If you already are running one of https bindings it’s very simple.

The worst part is trying to understand vanilla IIS / SSL. Luckily that is generic knowledge any good IT person should either know or when they learn it it will be applicable everywhere. #NoThrowAwayKnowledge #NoSurprises


(Bart Elia) #17

Now that’s not what I mean, don’t get me in trouble :wink:

The whole point is reaching out to folks who go beyond the scripted help and try to apply technology in areas that even Epicor hasn’t considered. And trust me we consider a ton behind closed doors - Being able to execute on it, have it be stable, easy to migrate to, supportable all are critical aspects to things beyond oh this is cool tech. It may be but at the end of the day we need to provide you folks business value. That’s what we are supposed to be bringing to the table like any group you deal with. I could go to the farms in the area for my veggies (and do with the grand-kids) but a store is usually a little easier to do one stop shopping. We respect that and consider you folks all the time in our conversations to bring our customers forward in ways that makes sense.


(Bart Elia) #18

Has LetsEncrypt been added to Microsoft Trusted Root authorities?


(Jose C Gomez) #19

Yes sir! They are also cross signing so it’s valid even before it’s a direct root cert was added


(Bart Elia) #20

Trying to tease that apart in their docs. I really do like the MS way of adding / revoking cert authorities out of band with other services - or roll it out in Group Policy.
I don’t see LetsEncrypt or IdentTrust name in the trusted roots though. How is a client able to do third party assurance the certificate is legit?