RESTful Question for Support - Exposing Aware Data

BenHayat

@ Support;

When we expose an Aware Process as a service to outside world via REST:

a) If this process is supposed to create a new object with certain data passed in, and we have validation rules on that object, and if the client sends invalid data, how do we respond back that the object can't be created. For example, Payment date must be equal to today or before. Basically, how do we communicate back errors to caller?

b) How can we authenticate that a service requester (i.e. a user from phone) is an authenticated user in the system?
How can we Authorized the user level and what processes they can call?
And Do we have to do authentication in every request?
And how do we reject an unauthorized or unauthenticated requester?
Another words, how do we do login into Aware using REST endpoint?

c) If a process that may take some time, how does Aware communicate back when the process is completed?

d) Does the client make the service request as in Synch or Asynch mode?

e) How will the service caller know a process has been completed by Aware?

Thanks!

BobK

Ben,

I am not support, but we have exposed several RESTful services. These are all called by our own internal systems, but I do not see any reason why a third party could not call them.

I will try to answer you question based on my observations of using these services.

A) In the data we return from these services we have a message field that either contains “success” or an error message. We do all of our validation in the called process, not with rules attached to the object. The reason being that if a rule attached to the object executes a REPORT ERROR when the object is being created, the object is not created, the called process is not executed (any Failure rules are also not executed) and an HTTP Status 500 returned to the caller. With the validation rules in the process, the object has already been created and we can set the message with any appropriate error message and the caller gets a more user friendly error message.

B) How can we authenticate that a service requester (i.e. a user from phone) is an authenticated user in the system?
We authenticate a user by requiring the loginname and password to be passed in with the incoming data. We then use the PWD_ENCRYPT function to encrypt the password and verify that the loginname and encrypted password match what is in the RegularUser table.

How can we Authorized the user level and what processes they can call?
Only the process (and any sub-processess) that is called by the service will be executed. It's not like they are logged in and have a menu of options to choose from. If you need to execute a sub-process based on their access level, you will need their loginname to be passed in the data then you can look up their access level.

And Do we have to do authentication in every request?
Each request is separate. If you require authentication, you need to do it with each request. If you do not require authentication, that is you allow anyone access to the service, you do not need to authenticate any request.

And how do we reject an unauthorized or unauthenticated requester?
On the services where we require authentication and the authentication fails (see above), we set the message field to an appropriate error message and that is all that is returned to the user.

C) When the process completes, AwareIM sends any response back to the caller. If the process takes a long time and the connection times out, you will have to redesign the service to complete sooner.

D) I do not know.

E) The caller will know the process completes when they get the response back. If the service is set to not send a response, the caller should not care when it completes.

Some gotchas to watch out for:

Make all Plain Text fields bigger than required. If the user sends data that is longer then the defined length, the process will bomb and return a 500 status. If you make the field bigger than required, you can check the length and return a user friendly error message if they send more data than allowed. The process will still bomb if they send data longer than the defined length, but the bigger you make it, the less likely that will happen.

Make all fields Plain Text fields. If you define a field as a number, and the user sends not a number, the process will bomb and return a 500 status. With a text field, you can check that the data is a number and return a user friendly error if it is not.

BenHayat

BobK wrote
Ben,

I am not support, but we have exposed several RESTful services.

Thanks Bob;
Just like it's desktop counterpart, all service calls actions and data are private, meaning it belongs to a specific user. So do I understand correctly that with every call,
a) the caller must pass in user Name & password
b) Service then searches for userName
c) If found, checks if password matches the encrypted password in DB
d) if match is correct, then the service has the user in context to begin working on any other object that relates to the user in context, which is like a "LoggedInUser" in desktop mode.

So, with every service call we need to do these 4 steps at all time. Does it sound right.

The fact that Aware bombs out if data type doesn't match, is a big problem. We can't change the existing structure of DB to be all text. That would break all existing code.
Which means with every call, we also have to perform allot of data validations with every attribute before a process is run. Another words, all processes for service calls must be a custom "Remote Procedure Call" (RPC).

BenHayat

Another question that I have is the returned data.

Let's say the caller needs all today's orders and each order's line items. Another words, with ONE call, the service needs to send back a json package with all orders and each order to have it's children line items as one package. This way, when the caller gets it, it automatically gets parsed into receiving system to show orders and it's line items.

Is it possible for Aware to deal and bundle this type of data packaging?

BobK

BenHayat wrote
Thanks Bob;
Just like it's desktop counterpart, all service calls actions and data are private, meaning it belongs to a specific user. So do I understand correctly that with every call,
a) the caller must pass in user Name & password
b) Service then searches for userName
c) If found, checks if password matches the encrypted password in DB
d) if match is correct, then the service has the user in context to begin working on any other object that relates to the user in context, which is like a "LoggedInUser" in desktop mode.

So, with every service call we need to do these 4 steps at all time. Does it sound right.

That is mostly correct. Just to be perfectly clear, the service does not do the search/checking for the userName and password. Since the user is not actually logged in, you do not have the LoggedInRegularUser automatically in context. You need to code the FIND RegularUser WHERE LoginName = <passed in name> AND Password = <encrypted password passed in>. If it is found, it is then in context just like any other object found.

BenHayat wrote
The fact that Aware bombs out if data type doesn't match, is a big problem. We can't change the existing structure of DB to be all text. That would break all existing code.
Which means with every call, we also have to perform allot of data validations with every attribute before a process is run. Another words, all processes for service calls must be a custom "Remote Procedure Call" (RPC).

Unless whoever is calling your service can guarantee the data will be in the correct format, you will need to validate everything. That is why we use an intermediate BO for the incoming data. After all validation is passed, then we create/update the actual BO from the intermediate BO.

BobK

BenHayat wrote
Another question that I have is the returned data.

Let's say the caller needs all today's orders and each order's line items. Another words, with ONE call, the service needs to send back a json package with all orders and each order to have it's children line items as one package. This way, when the caller gets it, it automatically gets parsed into receiving system to show orders and it's line items.

Is it possible for Aware to deal and bundle this type of data packaging?

Yes it is possible.

in the service definition, where you select the Return object, also select "Return multiple instances".

Using you example: if the Return Object was orders then all orders in context would be returned along with any reference objects, assuming line items were reference items.

BenHayat

BobK wrote
Using you example: if the Return Object was orders then all orders in context would be returned along with any reference objects, assuming line items were reference items.

Are you sure, If I bring all qualified orders into context, their referenced items are also INCLUDED or brought into context at the same before Aware serialize them into json and send it back?
I've always thought we only get one collection of data based on a specific object. How does Aware know which referenced objects to load into context and which ones not to?
For example in .Net if If building a collection of orders I can also tell it to "Include" items for each order and it will create another collection in memory (context) of items, and at the time of serializations they all get bundled into a single json file.

BenHayat

BobK wrote
That is mostly correct. Just to be perfectly clear, the service does not do the search/checking for the userName and password. Since the user is not actually logged in, you do not have the LoggedInRegularUser automatically in context. You need to code the FIND RegularUser WHERE LoginName = <passed in name> AND Password = <encrypted password passed in>. If it is found, it is then in context just like any other object found.

I wrote a long post with a new design idea of service login and custom session. Somehow, when I posted it, it never got posted and I lost all the stuff I wrote. :mad:

BobK

BenHayat wrote
Are you sure, If I bring all qualified orders into context, their referenced items are also INCLUDED or brought into context at the same before Aware serialize them into json and send it back?

I don't know how it works or when Aware brings the referenced items into context, but yes ALL referenced items will be in the json. At least for 1 to n peer relationships. I have not tried other forms of relationships and only assume (possibly incorrectly) that they would work too.

FYI: all attributes and referenced items will be returned to the caller. If you want to limit what is returned, you will have to do more work.

BenHayat

BobK wrote
BenHayat wrote
Are you sure, If I bring all qualified orders into context, their referenced items are also INCLUDED or brought into context at the same before Aware serialize them into json and send it back?

I don't know how it works or when Aware brings the referenced items into context, but yes ALL referenced items will be in the json. At least for 1 to n peer relationships. I have not tried other forms of relationships and only assume (possibly incorrectly) that they would work too.

Thank you Bob, that's a big relief.

FYI: all attributes and referenced items will be returned to the caller. If you want to limit what is returned, you will have to do more work.

I see, so Aware just returns a full object. That's not good, to send unwanted data. Even if we use PROTECT on certain attributes, they sill get sent?

It seems like I may save some time using Aware as a "REST service" but end up spending a lot more time (lack of security, session management and data protection) to build all these than, write a first-class citizen Web service in another platform that has all the standard REST an OData protocols built in...

BenHayat

BobK wrote
FYI: all attributes and referenced items will be returned to the caller. If you want to limit what is returned, you will have to do more work.

Bob, I've been thinking of this comment, and wanted to run it by you from Aware's point of view.

In order framework, say we have a Customer class/model that contains all customer's properties. However, for certain situation, I may only want to pass a class of Customer that has 3 properties and not the full class. So, I can create a ViewModel for that customer that is made up of only 3 properties and use that instead.

In case of Aware, if I don't want to send my entire customer object to the caller, how do we create a ViewModel (MiniCusyomer BO) that has less data and at the same time has the same data values that is in the original object like customer object? Should we create another BO with Shortcuts to main object and pass that one?

BobK

BenHayat wrote
In case of Aware, if I don't want to send my entire customer object to the caller, how do we create a ViewModel (MiniCusyomer BO) that has less data and at the same time has the same data values that is in the original object like customer object? Should we create another BO with Shortcuts to main object and pass that one?

We create a mini BO of our main object with just the attributes we want to pass. To populate the mini BO, we move the data from the main BO to the mini BO (example: miniBO.name = mainBO.name)

BenHayat

BobK wrote
BenHayat wrote
In case of Aware, if I don't want to send my entire customer object to the caller, how do we create a ViewModel (MiniCusyomer BO) that has less data and at the same time has the same data values that is in the original object like customer object? Should we create another BO with Shortcuts to main object and pass that one?

We create a mini BO of our main object with just the attributes we want to pass. To populate the mini BO, we move the data from the main BO to the mini BO (example: miniBO.name = mainBO.name)

Thanks for the confirmation.