3. Representational State Transfer (REST)

Representational State Transfer, from now on called REST, is actually not really a protocol, but merely a style of communication. Great advantages of having no protocol are simplicity, visibility and performance. A disadvantage is that the communication is not strictly defined, and therefore needs to be documented in a sufficient way.

Calling a REST service

Calling a REST service is done by URL. This means that all the information that the server needs, to process your request, is part of the URL (this is not entirely true due to HTTP headers, but close enough). Here is an example of a REST web service that allows you to receive information on currency exchange rates:

Go ahead, click on it to see what the exchange rates in 2024 for the Euro vs. the American dollar were. Your answer may look something like this:

{
  "data": [
    {
      "country_currency_desc": "Euro Zone-Euro",
      "exchange_rate": "0.927",
      "record_date": "2024-03-31"
    },
    {
      "country_currency_desc": "Euro Zone-Euro",
      "exchange_rate": "0.935",
      "record_date": "2024-06-30"
    },
    {
      "country_currency_desc": "Euro Zone-Euro",
      "exchange_rate": "0.893",
      "record_date": "2024-09-30"
    }
  ],
  "meta": {
    "count": 3,
    "labels": {
      "country_currency_desc": "Country - Currency Description",
      "exchange_rate": "Exchange Rate",
      "record_date": "Record Date"
    },
    "dataTypes": {
      "country_currency_desc": "STRING",
      "exchange_rate": "NUMBER",
      "record_date": "DATE"
    },
    "dataFormats": {
      "country_currency_desc": "String",
      "exchange_rate": "10.2",
      "record_date": "YYYY-MM-DD"
    },
    "total-count": 3,
    "total-pages": 1
  },
  "links": {
    "self": "&page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "first": "&page%5Bnumber%5D=1&page%5Bsize%5D=100",
    "prev": null,
    "next": null,
    "last": "&page%5Bnumber%5D=1&page%5Bsize%5D=100"
  }
}

This answer is in JSON format. The corresponding schema is hopefully placed in the documentation (such as an OpenAPI fileor any other type of documentation) of the web service.

If not, you will have to generate your own schema on this answer and hope that it is correct. This is the largest drawback of REST services. Luckily the documentation of the API of the example can be found here: https://fiscaldata.treasury.gov/api-documentation/

Now, lets look again at the URL:

https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/rates_of_exchange?fields=country_currency_desc,exchange_rate,record_date&filter=country_currency_desc:in:(Euro%20Zone-Euro),record_date:gte:2024-01-01

The URL consists of several elements:

• The first part is the location of the webservice (https://api.fiscaldata.treasury.gov)
• The next part is a fragment (/services/api/fiscal_service/v1/accounting/od/rates_of_exchange). Fragments are used to supply information to the web service. This particular fragment indicates that you want to retrieve the exchange rates from the v1 endpoint. 
• Everything after the '?' are arguments. They essentially are also just information for your request. In this example the argument determines the filter of the data set. You may for example change Euro%20Zone-Euro to Canada-Dollar.