Status of /help and /js

Topics: Web Api
Jun 6, 2011 at 2:39 PM

Hi guys,

Do you have any plans for includes in the WebAPI for generating help pages and/or js proxies?

We are seriously considering writing our own proxy generator but if it's in the roadmap we are going to wait.

Any news on this?

Thx,

Gerben.

Coordinator
Jun 6, 2011 at 5:45 PM

We are looking in to providing automatic help pages but have not locked yet on how it will look. We're exploring what would be the best solution for properly reflecting HTTP/Restful services. For example potentially having help pages that describe the media type (payload) rather than the service itself. What are your needs here? One option that some folks are exploring for now is to create a custom formatter for emitting a help page.

The RIA team I believe was exploring emitting js proxies. What were you looking for here?

Thanks
Glenn

Jun 8, 2011 at 11:40 AM
Edited Jun 8, 2011 at 12:00 PM

Hi Glenn

On the Help pages;

Difficult to say. I'm sure you have better ideas on that than I have. We're just looking to provide some sort of basic (dynamic) documentation to our services. I'm thinking:

- output/input parameters

- operation names and description (btw. we're missing [OperationContract(Description=...)], but that's more of a wcf thing probably).

- supported http methods.

- Advanced feat: get a sample post/get body format in the help. You could provide an interface which would ask the (de)serializable types to provide a sample for their json, xml (or whatever)

On the js proxy;'

I would be really disappointed if this wasn't included. We're working on it now and it's really not that hard, some ideas that we're implementing:

- A request to http://myhost.com/myroutingtableprefix/js examines is 'caught' by a channel if the mimetype is application/javascript or text/javascript. Channel examines the DataContract and returns javascript. HttpCode = OK. ContentType = 'text/javascript'. Request is cancelled (!)

- If project is DEBUG: Loads of comments are included. console.log lines. Whitespace is allowed, not minimized. etc.

- If project is RELEASE: No comments in generated javascript. No console.log, Whitespace minimized etc.

- Were are thinking of adding culture for error messages, so http://myhost.com/myroutingtableprefix/js&culture=en-US will generate javascript with English error messages ("could not connect to REST service", "No valid xml returned", and so on).

- Here again we are missing the OperationContract(Description=...) because we would like to add it to the javascript.

- Advanced feat: Examine the faultcontract to provide neat exception handling on the client??

- Advanced feat: DON'T GENERATE JQUERY! I know that's what you guys would like (and I understand) but we have a client framework consisting of thousands of lines of dojo code and jquery as an additional include is estetically not wanted.

- Maybe more to come, we're thinking about it.

Thx so far.

Gerben.

Edit: forgot to mention; our client methods will look like this, note that GetEmployee is a server method from the DataContract:

dojo.provide('hrvolution.proxy.EmployeeStore');
dojo.declare(
  'hrvolution.proxy.EmployeeStore'
  null, {
    GetEmployee: function(subject, customer, employee) {
      var returnData = null;
      dojo.xhrGet({
        url: 'myresturi',
        handleAs: 'json',
        headers: {
          'Accept': 'application/json'
        },
        sync: true,
        load: dojo.hitch(this, function (responseObject, ioArgs) {
          returnData = responseObject.adpmessage.domainobject;
        }),
        error: dojo.hitch(this, function (responseObject, ioArgs) {
          alert('Something went wrong: ' + responseObject + ' ioArgs: ' + ioArgs);
        })
      });
      return returnData;
    }
});