Consuming modules, shell commands

Probably you have already created a command module, you have it as a Restful Framework package using the whole project template and now is time of consuming your command module.

First step: install package in Restful Framework server.

Do you have a Restful Framework Server account? If not, please go first to https://restfulframework.com/login and register there your account.

In order to install a package you need to have an application registered in our servers. Login into our Restful Framework Server using your account at https://restfulframework.com/login and once you get to dashboard, press Add application button. Give a name to your new application and press Confirm button.

Ok, now you got a new application in your list. Click on the newly created application and now you will be in Configure application dialog.

Finally, browse your computer and locate your command module package (the ZIP file generated by Visual Studio project in your output path, for example /Bin/Debug). Open the file and Web interface will automatically upload and install your package.

Second step: authenticate your requests

Restful Framework Server is a HTTPS, JSON Web service. It only accepts POST HTTP verb.
  • Web service URL is: https://restfulframework.com/applications/appkey/shell/
  • Web service shell operation URL is: https://restfulframework.com/applications/appkey/shell/cmd

Another detail is any request to the server must be authenticated.

An HTTP POST request to Web service shell operation URL must contain these HTTP headers:
  • Restful-Authentication-UserName. It is the user name that registered the application hosting your command module.
  • Restful-AppKey. The application "app key" for the one hosting your command module.
  • Restful-Globalization-Culture. The culture name (for example, en-US) for the request.

Additionally to above HTTP headers, depending on if caller needs to be authenticated or it has been already authenticated, there are some special headers.

A. Your client is not authenticated

In this case, you need to add this header:
  • Restful-Authentication-Attemp. It should be a JSON object having two properties:
    • UserName. The user name of the user that will authenticate the request.
    • Password. The password of the user that will authenticate the request.

For example: { "UserName": "TestUser", "Password": "1234" } .

If your request gets authenticated, response will contain two HTTP headers that you must save for the subsequent requests:
  • Restful-PassKey
  • Restful-Authentication-UserToken

B. Your client is already authenticated

After a first request to Restful Framework Server that had a successful authentication, subsequent ones will not be sending plain credentials anymore.

Instead of that, subsequent request will be sending the Restful-PassKey and Restful-Authentication-UserToken headers obtained from the first successful authenticated request.

Third step: make your command request!

Put your command text as your request content and post it.

Fourth step: receive response

In the case that your request got processed in the right way, you will be receiving a response where response data is a JSON serialized object having these standard properties:
  • Message. It is a human-readable message sent by the command which contains information about the operation itself.
  • Status. It is a numeric value with these possible values and meanings:
    • 0: Undefined: No status. Who knows what happened?
    • 1: Success: Operation ended successfully.
    • 2: Warning: Operation ended successfully, but something should be taken in account.
    • 3: Error: Operation had an error.
  • Errors. This is a collection of errors. Each error has these properties:
    • Id. An unique identifier for the error.
    • Text. A human-readable reason text for the error.
    • AffectedResources. This is a collection of more specific information about the error. It is a dictionary where key is the field, resource or identifier affected by the error, and value is a human-readable text explaining what failed in the whole resource.

In order to read this object your client platform should have a JSON serializer capable of deserializing objects too (nowadays most of them have this capability).

Last edited Jul 4, 2012 at 1:27 PM by MFidemraizer, version 1

Comments

No comments yet.