Where can I find the 'SmartConnector REST API Gateway' document

[SteveGregory]

Where can I find the 'SmartConnector REST API Gateway' document that is referred to in the Installation and Configuration guide?

[sesa180908_brid]

Steven,

That document is currently in review and should be posted to this forum no later than the middle of the month.  

[SteveGregory]

Thanks Mark, I am just trying to set up and test the REST Api. Previously I have used one the UK team built and I want to compare the functionality but I can't seem to work out where to set up the connection to the SBO server. Is it in the REST Endpoint configuration or somewhere else?

[sesa180908_brid · Accepted solution]

All of the functionality that the UK team had should be in there: plus full authentication, API throttling, and Swagger integration.

That said, we did take a different approach and made the API truly "RESTful" and not just a port of EWS to REST.

The implementation is layered with a generic API and configurable "Data Providers" which will get data from different sources.  Two Data Providers are currently included: one for native SmartConnector EWS Server and another for any EWS Server over SOAP.  (A native SBO provider is currently in the works that will functionally replace the SOAP one for SmartStruxure communications).  The beauty with this approach is that once you've coded to the API, nothing on the client needs to change since the API is agnostic to the Data Provider.

Here is some content from the guide that should help get you started...

Provisioning endpoints is performed via the SmartConnector portal.  If you are not familiar with the SmartConnector Portal you should review section 5 of the SmartConnector Installation and Configuration Guide.

There are no restrictions to the number or type of REST endpoints you wish to provision in SmartConnector.  Regardless of the type, the process is the same however some configuration parameters will differ depending on the type of Data Provider used.

To provision a REST Endpoint in SmartConnector, perform the following:

1. Open SmartConnector Portal.
2. Select the Configurations-Endpoint menu option.
3. Click “Add New” from Endpoint Configurations page. 
4. By default, only one assembly will be available so select the “Ews.RestExtensions” assembly from the list. If others are displayed consult the Extension Author’s documentation.
5. Click the “Next” button.
6. At this point you have an option to choose one of the Data Providers available.  Select either Data Provider listed.
7. Click “Next”.
8. Edit the default Configuration Name and/or Description as desired.
9. Click “Finish”

SmartConnector will not immediately start the REST Endpoint because the configuration is not yet complete. If you click the “Validate” button, you will see what SmartConnector detects as issues.  The actual issues will depend on which Data Provider you chose in step 6 above. 

To complete the configuration, navigate to the “Endpoint Configuration” page for the REST Endpoint you wish to configure.  If you are following from the prior section, you will be on this page after completing the “Add” steps above.

The following parameters will be present regardless of the type of Data Provider you selected above. Those parameters which are specific to a Data Provider type are enumerated in the sections which follow.

When you click the “Details” tab, SmartConnector will display the details for the Data Provider you selected. 

• Scheme – The scheme, HTTP or HTTPS, of the endpoint.
• Host – The endpoint which is configured.  This can be either an IP address or DNS name as desired.
• Port – The HTTP port used.
• Base Route – An optional base or prefix route which occurs before the standard routes.

Expanding the “Http Configuration” node,

• Access Token Expire Time Span Minutes – The amount of time the authorization Bearer Token is usable. 
• Token Endpoint Path – The name of the route which is used to acquire the Bearer token.
• Serve Swagger Metadata – Whether or not Swagger and Swagger metadata are served.
• Name – How the Name of the endpoint will appear to Swagger users.
• Cache Tenant Id – Id of a SmartConnector InMemoryCache Tenant space allocated to the Data Provider.

There are more Http Configuration settings depending on which Data Provider you are using:

MongooseEwsRestProvider Configuration Parameters

• Server Address – The full SOAP endpoint for the EWS server which will be the data source.

SoapEwsRestProvider Configuration Parameters

• Ews Server Id – The ID of the SmartConnector EWS Server which will be the data source.

[sesa180908_brid]

And I just noticed that the last two parameters are transposed (and this is why the doc is in review)!

It should read:

MongooseEwsRestProvider Configuration Parameters

Http Configuration Settings

• Ews Server Id – The ID of the SmartConnector EWS Server which will be the data source.

SoapEwsRestProvider Configuration Parameters

Http Configuration Settings

• Server Address – The full SOAP endpoint for the EWS server which will be the data source.

[SteveGregory]

So the Ews Server Id would be something like "http://<SboServerIp>/Ecostruxure/DataExchange" ?

What about the Ews Server credentials? Where are they configured?

[sesa180908_brid · Accepted solution]

If you're connecting to SBO, you must use SoapEwsRestProvider.

For SoapEwsRestProvider

Server Address = EWS endpoint (e.g. http://localhost:8081/EcoStruxure/DataExchange)

For MongooseEwsRestProvider

Ews Server Id = ID of the server in SmartConnector's DB (that's found on the EWS Server page)

[SteveGregory]

Reading your instructions again I figured that out that much but cannot see anywhere to enter the SBO credentials. Are these passed in by the REST client?

[sesa180908_brid · Accepted solution]

Authentication isn't configured.  Authentication is done by means of a Bearer Token and must be supplied in an auth header by the client.

For testing purposes, the Swagger page allows you to enter credentials and try things out.   Go to the Status page in the Portal.  Click the Active Endpoints tab and then click the "Documentation" link.  A customized Swagger page will open in a new tab like below:

Use credentials for an EWS User in SBO and you should authenticate (red borders become green) when you click Login.  Then you can use any of the actions on the page.  Swagger will automatically add the auth header to every request. 

[SteveGregory]

Is there a way for the client to acquire/generate a bearer token?

[sesa180908_brid · Accepted solution]

Of course.  Authentication uses OAuth2 and it goes like this.

The client sends a POST to the Endpoint's authentication route.  That route is configurable (Bearer Token Endpoint Path) but the default is "GetToken".

The body of the route contains the credentials in the form:

grant_type=password&username=USERNAME&password=PASSWORD

The server responds with the Bearer Token.  The client then adds the token in subsequent requests in an "Authorization" header like this:

Authorization: Bearer BEARER_TOKEN_VALUE

The client can continue to use that token until it expires.  Expiration is configurable (Access Token Expire Time Span Minutes) but the default is 5 minutes.

[JeffBowman · Accepted solution]

Hi Steven,

If you are interested, I wrote a thread showing how to generate, configure, and use an autogenerated REST client using the Swagger documentation:
Generate client in Visual Studio for SmartConnector RESTful Endpoints

Regards,

-Jeff