Sample Endpoint with Method Code Example:
PUT   /truck/{truckId}

/truck/{truckId}  is one of the AZvehicles.com API’s endpoints with three methods, of which this is a PUT call.  It uses a unique truckId to update a specific truck from the collection with one or more of the truck’s characteristics stored as its “form data.”

Currently each AZvehicles’ form data consists of the following four characteristics:  a truck’s make;  model;  year;  and color.

Request Parameters

truckId
The unique truckId, generated by the system and returned when a new AZ classic truck is posted to it for the first time, is a required parameter.  It’s an 8-digit numeric of data type integer and format int64. It’s also a path parameter and the curly braces around it indicate that, even though it’s part of the URL path, the original string “truckId” is replaced by the unique truckId.

Characteristics to be Updated
At least one of the four characteristics of the truck, stored as its form data, is required to be updated—and the four are passed, as request body parameters, in the general body of the request (more on this below).  Their data type is string.

Try Out a Request in the API’s SwaggerUI and View the curl (aka 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 trucks Resource (Swagger)UI page (at https://azvehicles.com/trucks-resource/).

While in the expanded Put  /truck/{truckId} section of that page, do the “Try it out” and “Execute” steps to view the responses from the system.  First select an existing truck from the collection’s inventory and enter its unique Id (let’s say it’s 87654321) as the path parameter.

For the truck’s four form data characteristics, let’s say you’ve chosen Dodge as the make, Ram as the model, 1972 as the year, and blue as the color.  Then you’ve updated the color to purple (why not?) to finalize your four request body parameters.  After hitting Execute, the feedback will include the following curl call that represents your updateTruckWithForm  request call:

curl   -X PUT “https://azvehicles.com/azstc2018api/truck/87654321” -H “accept : application/json”      -H  “Content-Type: application/x-www-form-urlencoded”    -d “make=Dodge&model=Ram&year=1972&color=purple “

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 (the Resource URL), and the Request Body

As shown in the above curl call, the full request URL for this specific endpoint and method is:
https://azvehicles.com/azstc2018api/truck/87654321

This full path is often called a resource URL. You can refer to the two main parts of this resource URL by the following terms:

  • Base Path:  azvehicles.com/azstc2018api
  • End Path:  /truck/87654321

Note that the end path is what we refer to as one of the endpoints for the Trucks resource, and recall that this endpoint, /truck/{truckId}, can be used with two other methods besides Put (namely Get or Delete).

About Query Strings
Along with path parameters, a query string is one of the two types of parameter which can be part of the full request URL. A query string consists of a question-mark ( ? ) that immediately follows the endpoint and all of the data immediately following it. All this data must be URL-encoded with the individual pieces of data concatenated, in any order, by an ampersand ( & ).

The Request Body
Note, however, that there’s no such query in PUT /truck/{truckId}.  Instead, the updated truck information is passed—separately from the URL—as data, following the curl data command ( -d ), within the general request body as follows:
-d “make=Dodge&model=Ram&year=1972&color=purple “

The Response Body

If successful, the server response will be an object that confirms the updated set of the truck’s four characteristics from the form data, along with its unique identifier.

The following two sections of code show the returned object with the identifier and four pieces of form data from above, first in json and then in xml.

In JSON:{
“id”: 54321,
“make”: “Dodge”,
“model”: “Ram”,
“year”: 1972,
“color”: “Purple”
}

In XML:

<?xml version=”1.0″ encoding=”UTF-8″?>

<Truck>
<id>54321</id>
<make>Dodge</make>
<model>Ram</model>
<year>1972</year>
<color>Purple</color>
</Truck>

Overall Data Model for PUT /truck/{truckId}

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 the API’s Resource (Swagger) 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 (Swagger)’s endpoints, with each of their possible methods, in the form of a brief descriptive phrase.

For example, “Update Truck by ID,” in the trucks Resource (Swagger)’s sub-menu, is the brief phrase for PUT /truck/{truckId}.  Selecting it links you to the full Schema/Model webpage for this endpoint-with-method. ( Or you can just link to it here:   https://azvehicles.com/update-truck-by-id/  .)

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.  Note that, as an alternative—when you click on each of the different Resource (Swagger)UI  webpages themselves—you’ll see that, following its series of expandable endpoints-with-methods, it has an applicable data Models  table as well.

This alternative Models table is also valuable, and is more immediately accessible than the larger, separate data Schema/Model pages, but the latter provide the most information.  And, at least in Windows, it’s fairly easy to open the relevant Schema/Model webpage in a separate browser window from its overall Resource (Swagger)UI webpage so you can view the two webpages side-by-side as you expand and try out each of the endpoints-with-method sections on the Resource’s webpage.