Try the API!

MotorBase API Mock Server

Spring Point created a mock server¹ for you to test the MotorBase API, and in this document we outline two ways to interact with it:

• • through the command line using cURL or

  • visually, using a browser add-on.

Using cURL

The best way to try our API is by using a command line tool, such as cURL (strongly recommended).

cURL is a command line utility for transferring data using various protocols, including HTTP which is used by the MotorBase API. cURL is free and very popular; more information can be found here.

cURL is also a great tool for interacting with many other API's, such as twitter, Amazon S3, Facebook, etc.

• • cURL Installation

Windows MSI Installation:

http://www.confusedbycode.com/curl/

For other O/S, go to the official website:

http://curl.haxx.se/download.html

• • jq Installation (optional)

jq is a tool that pretty-prints JSON responses. It's useful for seeing JSON responses formatted for better human reading. Downloading this tool is optional, but recommended for easier reading:

jq Download Page:

https://stedolan.github.io/jq/

Important: depending on how you choose to install these tools, you may need to manually update your %PATH% environmental variable to point to the directories where they're installed.

Submitting a Purchase Order using cURL

In the Home page, copy the JSON data under "Example" in the "Data Params" section. Paste it onto your favorite text editor and save the file locally as "samplePO.json" (or any other name you choose).

Open a terminal, or Windows command prompt, and navigate to the directory where you saved the file above. E.g.: cd \users\myname

Then type this command to send your request:

curl http://testco.motorbaseonline.com/api/v1/purchaseOrders -H "x-access-token: testToken" -H "Content-type: application/json" -d @poFile.json -X POST

The -H flag specifies the HEADERS we need to include in each HTTP request:

• • Content-type: application/json

• x-access-token: testToken

With Content-type we're specifying what we're sending to the server: JSON (it could be HTML or XML for example).

The x-access-token is a key you get after you login to the API. Every request, except login, requires this header or an HTTP 403 (forbidden) error is returned.

Since this is a mock server, we simply use "testToken" for now. In a production environment you'd use a real key.

The -d flag is the data to send with the request. To specify a file, prefix its name with "@".

The -X flag specifies the HTTP method we use: POST in this case. If omitted, the default is GET. Notice that if the correct HTTP method isn't specified, you will get an HTTP 404 error in this example.

After executing the command above, you should get this response:

If you chose to install jq, you can pipe cURL's output to jq for pretty-printing the JSON response. Notice the red-colored font below:

curl http://testco.motorbaseonline.com/api/v1/purchaseOrders -H "x-access-token: testToken" -H "Content-type: application/json" -d @poFile.json -X POST | jq "."

You can specify other flags in cURL, such as -i to display extra information about the response.

Note: the -i flag will not work with jq, as jq will not know how to parse (pretty-print) the extra information.

Where to go next

In the Home page, all the API resources contain working cURL examples at the bottom of each section. Try them out to see the MotorBase API at work.

Using a Browser Add-on

There are several choices for a browser-based RESTful client. You can simply search the Internet for:

"RESTful client for [your browser name here]"

And you can choose any one you want, as they all basically accomplish the same thing.

In this document, we'll use "Postman":

https://www.getpostman.com/

Once you download and install Postman, follow the steps below. It's worth mentioning again that using cURL is usually quicker.

Step 1

• • Open Postman

  • In the request URL field enter: http://testco.motorbaseonline.com/api/v1/purchaseOrders

  • Next, select the HTTP method as POST.

Step 2

• • Click on the "Headers" tab then on the "edit" icon as shown below.

Step 3

Enter the following header information:

• • Content-Type: application/json [hit enter]

• x-access-token: testToken

With Content-Type we're specifying what we're sending to the server: JSON (it could be HTML or XML for example).

The x-access-token is a key you get after you login to the API. Every request, except login, requires this header or an HTTP 403 (forbidden) error is returned.

Since this is a mock server, we simply use "testToken" for now. In a production environment you'd use a real key.

Click "Done".

You should see the headers populated:

Step 4

Enter the data to send:

• • Select the "Body" tab

  • Click on the "raw" radio button

  • Then simply enter an empty array for now: []

We'll submit a real Purchase Order later.

Click "Send".

You should see an ERROR response from the API indicating the Purchase Order array is empty.

That's it!

To actually submit purchase orders, simply copy the example from the Home page and paste it in the Body request:

Next, feel free to edit the purchase order example to create your own. If the example becomes invalid, the API will clearly point that out as an error response.

¹Usage and Privacy Notice

Most of the time our mock server will not persist any data you submit, nor will it validate your HTTP requests against any data source. However, at our discretion we may choose to log your requests, and in such cases any data you submit may be persisted in our servers. By using this service you agree that Spring Point isn't liable nor responsible for the content you choose to submit. We may choose to stop providing this service at any time, without any notice. For other conditions and rules, please see our Terms of Service.