On 10/30/07, Stefan Hübner <sthuebner@...> wrote:
> Hi all,
>
> I'm designing an API which exposes data like companies, products, etc..
>
> To access company-data the API defines URLs like this
> "/companies/<id>", and for product-data URLs look like this
> "/products/<id>". This way I can search for companies with a URL like
> this "/companies?name=<pattern>" or for products with URLs:
> "/products?name=<pattern>".
>
> Then I thought, products actually belong to the companies producing
> them. So I came up with this product-URL:
> "/companies/<comp-id>/products/<prod-id>".
>
> But here's my problem now: how should a search be designed which is to
> search among all products of all companies - a global product search
> that is? "/companies/<comp-id>/products?name=<pattern>" doesn't work
> globally - at least it shouldnt.
>
> Am I to expose something like "/search?type=products&name=<pattern>"
> or are there reasonable alternatives?
>
> Or am I better off with the first approach?
>
>
> How would you design such an API?
>



You don't say this explicitly, but it sounds like "designing an API"
means, you are designing a formula that programmers of client programs
can use to construct a query url.

If that is what you mean, well, I wish we'd do less of that.

The form of a query url should only be important to the server
implementor. The server should deliver an HTML form or Xform or some
such, that tells the client to fill in some blanks, and then using the
rules of HTML forms, the client composes the URL.

When you do that, it won't matter if you decide for queries the one
way, then three weeks later decide to do it the other way, or some
third way.

If this is machine to machine communication, it amounts to telling
developers to look for <input> elements named "product-id" and to form
the url according the rules of the forms language, e.g. append
"?name=value..." to the form's action attribute.

I admit I'm not sounding very convincing with this argument, because
I'm asking you a) to have clients make an extra GET first to retrieve
the form, and b) they still have to have some foreknowledge of the
element name attributes they should understand. It does however
insulate them from having to understand the form of your urls.

I guess I'm putting this out here for discussion, and not really
suggesting you implement it this way. But if anyone out there thinks
there's a good way to do what I'm trying to do, which is to drive the
interaction through forms, please jump in.



Hugh