0

Let's assume we have a RESTful web service that will calculate UK Royal Mail postage charges.

There would be a number of essential input parameters: weight of item (grams, int), length of item (cm, int), width of item (cm, int), category of item (letter/parcel, string/enum), service required (first class/second class/special delivery/etc, string/enum), destination (domestic/international/maybe further specify the latter, string/enum)

Such an application would be easy to create as a WebAPI. It could be called via a URL such as ... http://myserver.com/api/mailcharges?weight=150&length=15&width=10&category=letter&service=first&destination=domestic

The web service would then do a simple lookup on its internal tables and return the postage in its response payload.

The beauty of this is that it could then be utilised by a variety of applications within an organisation (or even outside it!). However, this requires that each application that calls the web service needs to be able to populate these parameters; the integers are OK, they are just that - numbers. But the strings or enums are more difficult. The logic for entering and validating these needs to be replicated in every client application. Wouldn't it be nicer if the web service could prompt the user for any which are not passed in or passed as nulls or invalid values. In fact wouldn't it be nicer still if the web service had a user interface which allowed a user to enter any or all of the parameters.

What I am looking for is a cross between a web site and a web service. A web application which can be called via a simple RESTful http request, which pops up a user dialogue, accepts user input, and when the user clicks on a suitable button, does its calculation and returns its answers as a JSON/XML response.

Does anyone have any ideas on how to implement such an architecture? I have tried calling MVC actions/views from within a web api controller but the response is the html for the MVC view, and is returned to the api controller directly rather than being rendered and POSTing back its user input.

I hope I am just being thick, and that the answer is obvious, but all my experiments have so far failed, and any suggestions, no matter how far fetched or outrageous, would be very welcome.

I realize that this is a fairly trivial example, but the same argument goes for much more complicated web services where the replication of user input forms, input validation, complex processing logic etc. across multiple client applications would be far more of an issue than with this example.

Tony Bater
  • 327
  • 6
  • 17

1 Answers1

0

if the web service could prompt the user is essentially missing the point of a service. It is no longer a webservice, but a webpage.

In order for internal/external applications/websites to utilize your service, they essentially need to know three things:

  1. where to ask - this is your http://myserver.com/api/mailcharges
  2. what are the arguments - that is weight, length…
  3. what are accepted argument values

While 1. and 2. are usually mere API documentation you seem to have a problem with p. 3 - you want the user to be somehow prompted to choose among possible values and not guess. But you also want the user application not to be responsible for maintaining/validating the list of possible values.

Guess what? You simply need another API. :) An API to describe your arguments.

Let's concentrate on category field. Your API could be extended with a new URL: http://myserver.com/api/getCategories which essentially returns a list of available (currently understood by API) possible category values. This can be JSON, or comma separated string or whatever reliable. Now your end-user GUI-enabled application calls the API, asks for categories, and creates UI accordingly - populating ComboBox or whatever with obtained values. The same is done for other fields. You can. i.e. obtain acceptable ranges of weight or length.

The important thing you mention in your question is validation: logic for entering and validating these needs to be replicated in every client application. This is somehow true, as it essentially depends on the technology used in the end-user application. On the other hand it is very important, that the API performs validation itself! You can never know who is going to use your API. And it is always better to check twice then never.

Kuba Wyrostek
  • 6,163
  • 1
  • 22
  • 40
  • Thanks Kuba. I appreciate what you say, and I understand the comment about missing the point of a service no longer being a service but a web page. Perhaps I asked the wrong question and should have asked "How do I get a web page to return a data packet to its caller?". I have considered the extended api solution (getCategories etc.) before, but I wanted a single user interface for the user input, rather than similar user interfaces in each application (which may be developed by different teams and therefore use slightly different approaches). – Tony Bater Jul 01 '15 at 15:40
  • In any case, disregarding the naming, I hope the answer solves your problem. – Kuba Wyrostek Jul 01 '15 at 15:41
  • Also, why build the user interface more than once? The only solution I have come up with is to compile my user interface into a class library and then reference it and build it in each of the client applications, but I was trying for what seemed like a simpler solution! – Tony Bater Jul 01 '15 at 15:45
  • Whether you have one or more user interfaces is irrelevant. This is about separation of concerns. As you have stated yourself: the API *could then be utilised by a variety of applications within an organisation*. – Kuba Wyrostek Jul 01 '15 at 19:34