New to Web Services

This page is for those new to web services as a technology and who would like some background information. It is a whistle-stop tour through the salient features.

What is a 'web service'?

A web service can be defined as "A way of using the network to transfer data between applications". The following diagram offers the most basic illustration of this process.

Here we see a user application making a request for service over the internet to a web service and the web service responding. The service could do practically anything - query a database and give back some data, send emails, produce a specialized PDF report, etc.

In fact, you just used one very common form of web service - you pulled up this page on the World Wide Web. Whenever you type a URL into the address bar of your browser (your 'user application'), you are making a service request that says, 'Give me the web page that lives at this address.' The service responds with some HTML code that your browser displays as the web page on your screen.

The previous statement, that your browser says 'Give me the web page that lives at this address' isn't quite correct. What your browser really says is 'Give me the thing that lives at this address'. The URL could lead to a PDF file or an image or a piece of video. And the 'thing' need not always stay the same. It can be 'dynamic' - same URL, different result. The Google homepage is a good example of this, with its oft-changing logo. One day it's the standard logo, the next it may be modified to celebrate some historic event, but the URL is always http://google.com.

The dynamic things (we'll switch to calling these 'resources') are the most useful ones. NatureServe has dynamic resources that can be asked to supply information from the NatureServe databases - these are the NatureServe web services and they live at specific URL's, as shown in the service descriptions.

Asking for service

OK, we may know a service's URL, but how do we request something from it? There are 2 major flavors of how to do this:

• REST - REpresentational State Transfer
  Simply put, this works as described above, using URL's.
• SOAP - Simple Object Access Protocol
  This is a competing standard, with a much more 'programmer-centric' focus.

The pros and cons of each method are the subject of much debate. If you wish to delve into this, see the Wikipedia article on Web Services for a jumping off point. All NatureServe's web services use a REST interface, so we will not cover SOAP in what follows.

To request service from a REST web service, you need to know its URL and any parameters it might accept.

For instance, the Species Images Service lives at https://services.natureserve.org/idd/rest/ns/v1/globalSpecies/images. Going to that URL by itself produces the message that there are 'not enough parameters'.

The service description tells us that we must specify at least one of either UID, scientific name or common name. The simplest way to do this is to append the parameter to the URL.

We start by adding a '?' to the end of the URL. This tells us that the URL finishes here and a list of parameters follows it.

Each parameter thereafter is shown as a 'name=value' pair, for instance 'commonName=black*'. Where more than one parameter is specified, these are separated by a '&'.

Using our example, we can call the Species Image Service to search for images of species with common names beginning with the word 'black' by typing the following complete URL into a browser (or by clicking it).

https://services.natureserve.org/idd/rest/ns/v1/globalSpecies/images?commonName=black*

Once you've done that, change the word 'black' to 'blue' and try again. You'll see how parameters affect the service response.

Interpreting the response

As previously noted, a service can produce all sorts of responses, from simple HTML pages to PDF reports to Zip files of data. One common response format for data query services is XML, an example of which is the response to clicking the URL, above.

See the Technical Library for some XML learning resources, but, in short, XML is a little like 'HTML for data'. Where HTML uses tags to describe how to format a piece of text, e.g. <b>bold</b>, XML uses tags to describe the meaning of the text, e.g. <commonName>BlueJay</commonName>. This simple yet powerful approach leads to the easy dissemination and analysis of data.

Conclusion

You should now have a basic understanding of what web services are, at least enough to successfully understand the service descriptions for NatureServe's services. For people simply seeking one-off data, the browser may be all they require. For those interesting in making NatureServe data a part of their own applications, we refer you to the Code Samples.