Code Sample

An example API guitar catalog website

Sample Endpoint (with Method) Code Example:
GET  /car/findByMake

/car/findByMake is one of the AZvehicle.com API’s endpoints with just one method, a GET call that returns a list of cars filtered by make (Chevrolet, Ford, Chrysler, etc).

Request Parameters

This endpoint-with-method has the one parameter, Make, and it is a required, query parameter (which is also its location in the Request URL, see more below). Its form is an array of the 11 possible vehicle makes (from Buick through Pontiac), of the data type [string].

Try out a Request in the API’s SwaggerUI and View the cURL Request Call

If you haven’t already be sure to spend time, in the AZvehicle.com API Reference Documentation section, on the various Resource (Swagger)UI webpages—such as the cars Resource (Swagger)UI page (at http://azvehicles.com/cars-resource-swagger/).

While in the expanded GET  /car/findByMake section of that page, do the “Try it out” and “Execute” steps to view the responses from the system. Once you’ve selected, for example, Ford as your “Filter cars by make” choice and have hit execute, the feedback will include the following curl call that represents your findCarsByMake request call:

  • curl  -X GET “http://azvehicles.com/azstc2018api/car/findByMake?make=Ford” -H “accept: application/json”

curl Request Call and Your Front-End Request GUI

Since curl is a command-line tool providing a language-independent format for showing HTTP requests and responses, you can use it to build your Request UI in whatever front-end language you’re working in. NOTE:  For a comprehensive set of reference documents and tutorials for understanding and using curl, see its Tool Documentation page at https://curl.haxx.se/docs/tooldocs.html.

API Terms for the Parts of Your Request URL

As shown in the above curl call, the full request URL for this specific endpoint and method is:
http://azvehicles.com/azstc2018api/car/findByMake?make=Ford            You can refer to the parts of this URL by the following terms:

  • Base Path: azvehicles.com/azstc2018api
  • Path: /car/findByMake
  • Query: ?make=Ford

The Response Body

If successful, the server response will be an array object listing of all the cars currently in the collection that are of the specified make (in this case, Ford).  Note that if (UI permitting) the user selects more than one car make to return, the array returned will list the cars from all of the makes selected. In such a case, the query section of the request URL might look like the following:

  • ?make=Cadillac&make=Chrysler&make=Ford

The following section of code represents part of an array returned when the selected make is
simply Ford.

1	[
2	   {
3	      "id": 0000,
4	      "make": "Ford",
5	      "model": "Mustang",
6	      "year": 1972,
7	      "color": "Blue"
8	   }
9	   {
10	      "id": 0001,
11	      "make": "Ford",
12	      "model": "Galaxie",
13	      "year": 1964,
14	      "color": "Yellow"
15	   }
16	   {
17	      "id": 0002,
18	      "make": "Ford",
19	      "model": "Torino",
20	      "year": 1981,
21	      "color": "Red"
22	   }
.  .  .
23	]

Overall Data Model for GET /car/findByMake

To find the comprehensive schema (aka model) for each endpoint-with-method, you may have already noticed the following. After selecting the API Reference Documentation header on the azvehicles.com homepage, each of this API’s Resource categories in the resulting drop-down list is followed by an arrowhead ( > ) that, when selected, shows a cascading sub-menu. The sub-menu lists each of that Resource’s endpoints, with each of their possible methods, in the form of a brief descriptive phrase.

For example, “Find Car by Make,” in the car Resource’s sub-menu, is the brief phrase for GET /car/findByMake. Selecting it links you to the full Schema/Model webpage for this endpoint-with-method. The relevant Schema (aka Model) page is your most comprehensive source of information on each of the main data structures in the AZvehicles.com API. The various Model sections in the SwaggerUI for each endpoint-with-method are also valuable, and more immediately accessible than the Schema/Model pages, but the latter provide the most information. (And, at least in Windows, it’s fairly easy to open the Schema/Model webpage in a separate browser window from its endpoint-with-method –and overall Resource– page and then view the two webpages side-by-side.)