Sample Endpoint (with Method) Code Example:
POST /truck/{truckId}/uploadImage

/truck/{truckId}/uploadImage  is an AZvehicle.com API endpoint with just the one POST method as its call. Like the truck/{truckId} endpoint, it uses a unique truckId to identify a specific truck from the collection and then, in this case, uploads a picture of the truck to display with it.

Request Parameters

truckId
The 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 a path parameter and the curly braces around it indicate that, even though it’s part of the URL path, the string “truckId” is replaced by an 8-digit numeric of data type integer and format int64.

additionalMetadata & file
These are two pieces of additional data to pass to the server outside the URL path in the body of the request. Their content type is multipart/form-data, and the first is a web address as the source of the image file while the second provides the filename and file type for uploading. In both cases the data type is string. More on these parameters below.

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’s API Reference Documentation section, on the various Resource (Swagger) UI webpages (such as the trucks Resource page, at https://azvehicles.com/trucks-resource / ). While on the /truck/{truckId}/uploadImage  section, 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 additionalMetadata, enter the URL of the site that contains a picture of the truck as an image file (we’ll call it “www.yourwebpage.com/pix/truckpic” ). Lastly provide the filename of the image file (we’ll say “IMG_0157.JPG” ). After clicking Execute, the feedback will include the following cURL call that represents your uploadFile Request call:

curl -X POST
“https://azvehicles.com/azstc2018api/truck/87654321/uploadImage”
-H “accept: application/json”
-H “Content-Type: multipart/form-data”
-F “additionalMetadata=www.yourwebpage.com/pix/truckpic”
-F “file=@IMG_0157.JPG;type=image/jpeg

Some Explanations About the cURL Call

cURL is a command-line tool providing a language-independent format for showing HTTP requests and responses, which means you can use it to build your Request UI in the 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.

More specific explanations about the above cURL call follow:

  • The “-X” is a cURL command specifying the method to use with the request (in this case POST).
  • The two “-H” commands indicate a couple of custom headers:

The first, “accept: application/json”, specifies that the application will only accept a response in JSON format (Java Script Object Notation).

The second, “Content-Type: multipart/form-data”, specifies that the following two pieces of information will be passed, as an object, as if from an online form which a user has filled out and pressed the submit button for.

Note that the information here and in the following bullet comes from the full reference man page which can be accessed from the cURL Tool Documentation link referred to above.

  • The two “-F” commands are similar to cURL’s “-d” commands for passing data, but refer to the two pieces of content, together as an object, that emulate data from a form—as indicated in the preceding custom header:

The first piece of form data is labeled “additionalMetadata”, its data type is string, and its value is a specific URL or URI providing the location of the image file to be uploaded. In our example it is
www.yourwebpage.com/pix/truckpic

The second piece of form data is “file”, and its value is the actual filename (prefixed, in cURL, with an @), followed by a “type=” to specify the exact file type.  In our example this form data is ”file=@IMG_0157.JPG;type=image/jpeg”. The data type is still string, but the uploaded file will be binary in format.

API Terms for the Parts of Your Request URL

As shown in the above example cURL call, the full request URL for this specific endpoint and method is:
https://azvehicles.com/azstc2018api/truck/87654321/uploadImage
You can refer to the parts of this URL by the following terms:

  • Base Path: azvehicles.com/azstc2018api
  • Path: /truck/87654321
  • Query: When it’s present, a query string includes a question-mark ( ? ) at the end of the URL and all of the data following it. All of the data must be URL-encoded, with individual pieces concatenated by an ampersand  ( & ).

As we saw above, however, none of that applies to the PUT/truck/{truckId}/uploadImage endpoint. The specifics about the truck picture were passed separately from the URL, as form data following the cURL data command ( -F ), within the request body.

The Response Body

If successful, the server response will include the truck’s unique identifier accompanied by an image file, displaying a photo of the truck, that will now be a part of the truck’s information at the azvehicles.com website.

Overall Data Model for  POST /truck/{truckId}/uploadImage

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, “Upload Truck Image,” in the trucks Resource sub-menu, is the brief phrase for POST /truck/{truckId}/uploadImage. 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/upload-truck-image/ .)  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 at the end of 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.)