CODEWITHSUNDEEP
pythonrestarchitectureinterface
Roman Bodnarchuk
Roman Bodnarchuk

Reputation: 29727

Presenting REST web-service interface to clients

One of resources in my RESTfull web-service, which performs a search operation, has a lot of criteria/parameters.

In the current implementation this search criteria is passed like a dictionary with option mnemonics as keys. E.g.

{'fieldl_greater_equal' : <value>,
 'field2_like' : <value>,
  ...}

The questions are:

What is the best way to introduce list of allowed mnemonics and allowed values for each mnemonic (i.e. interface of the system) to my clients?

Should I move those mnemonics to inurl-parameters?

How to make such resource easy-extendable?

Any suggestions and receipts of how such system should be implemented?

Web-service is implementing on Python.

Upvotes: 2

Views: 177

Answers (2)

S.Lott
S.Lott

Reputation: 391952

First. "search" can mean almost anything. It helps to be very, very clear on what the use case is for your GET request.

You have three essential choices for "search".

  • Query String. ?param1=this&param2=that

  • Fragment. #param1=this&param2=that

  • URL path element. /this/that

The Path Element is something you use when the "search" is really using the primary keys to identify the resource. Paths don't change. This is the identity of the resource more than some kind of "search".

The Fragment is the very flexible, but also lives at the fringes of RESTful URI processing. You should probably avoid using it.

The Query String is what most folks think of when they think of "search" instead of "identification" of a resource.

Your URL components, however, can be fairly complex things. I've used a syntax like /in;param1=this;param2=that/ in a URL to provide more flexible identification of resources. We were making a claim that the URI would positively (and always) locate the resources. The "in" meant include. We had "ex" for exclude.

I try to avoid using ?param1=this&param2=that query string to identify a resource. I think it should used it for page numbers and other things that were not essential for identifying the resources.

No matter what you do, you need to provide a list of allowed param names and their interpretation. This is "metadata" and you can implement Metadata REST requests.

You define some "/api" or "/meta" API's which provide the information on the URI's, the parameters and how it all fits together.

Upvotes: 3

Dirk
Dirk

Reputation: 1903

One way to describe a REST webservice is by providing a WADL that describes how the service can be accessed. For a description of allowed values you could use some sort of schema definition (either JSON or XML) which allows for the defintion of enumerations of those.

This approach would allow automatic verfication, whereas you can always provide a free text description with illustrating examples in addition.

Upvotes: 0

Related Questions