Web service type: query or passthru?


Status message

New Feature: Guest Login function added to facilitate site exploration without registering. Try it out!

When creating an Araport web service, the developer's first task is to choose one of four implementation types.

  • query: This is the standard adapter type. Query adapters have the power we associate with server side computer programs. They read user parameters from the URL. They may filter, combine, or reject the parameter list. They use the parameters to formulate a query to the remote data source. They gather the returned results and possibly filter or combine them. They format a response to the user. For uniformity, the return type is guaranteed to be a valid JSON document. By default, the returned document includes meta-data about the execution of the query.
  • passthrough: This is the 'quick and dirty' adapter type. It does not process its input parameters and it does not process its output results. It simply passes its given parameters to the remote data source. It simply passes the results back to the user, no matter the format, content, or error status.
  • generic: This is like a query adapter but is allowed to return any data type. This type is best for delivering image files and compressed files.
  • map_filter: This is like a generic adapter but allows the data processing rules to be specified at run time.

Choosing the Right Type

  • Implement a query adapter unless there is reason to do otherwise. The end users will appreciate the guarantee on JSON results. The developer can easily use Araport to provide live "try it" documentation for every endpoint.
  • Implement a passthrough adapter if the remote service is perfect as-is. The adapter developer will not inject any logic at all. By remaining out of the loop, the developer will preclude any suspicion that his codes are causing errors. Other than using an Araport based URL, the adapter's users will deal directly with the remote data source behavior.
  • Implement a generic adapter for returning images and other non-JSON result files. (It is good design to offer a query adapter that runs a search and returns the image identifier, and a generic adapter that takes the identifier and returns the image. For best usability, the query adapter can return the fully formed generic adapter URL for that image.)
  • Implement a map_filter if you need to push the boundaries of web service design.

Specifying the Type

Araport web service adapters are required to provide self-descriptive meta-data. The meta-data belongs in a file along with the adapter source code in a public repository such as GitHub. The meta-data must be provided in a file called metadata.yml in the YAML format. (YAML is a very easy to use text-file format.) The meta-data file must contain one of these four choices:

  • type: query
  • type: passthrough
  • type: generic
  • type: map_filter