Edmunds API

This tutorial shows how to configure a remote web service to connect to the Edmunds Vehicle API. It shows how to pass parameters like API keys and format options to the remote service. The ones in this example are specific to the Edmunds API, but many APIs have similar concepts.

Create the Remote Web Service

• In the admin console, go to the Services tab and click Create.
• Set the Service Type to 'Remote Service' > 'HTTP Service'.
• Set the service name to 'edmunds'.
• Set the service label to 'Edmunds API'. Check the Active checkbox.
• Go to the Config tab for the new service and set the Base URL to https://api.edmunds.com/api/vehicle/v2/.
• Click the '+' button under Parameters to add a new parameter.
• Set the name to 'fmt' and the value to 'json'.
• Check the 'Outbound' checkbox so that your DreamFactory instance will pass the parameter through to the Edmunds API.
• Select all verbs so that the parameter is sent to the Edmunds API for all requests.
• Add a second parameter. Set the name to 'api_key' and the value to your API key issued from the [Edmunds developer portal http://developer.edmunds.com/].
• Check the 'Outbound' checkbox and all verbs.
• Click Create Service to save your new service.

Call the Remote Web Service

You can now use any REST client to access your remote web service using the DreamFactory REST API. See other tutorials for authentication options. To get a list of new vehicle makes and models for 2015 you would send the following request. Replace http://localhost:8080 with the URL for your DreamFactory instance.

GET http://localhost:8080/api/v2/edmunds/makes?state=new&year=2015&view=basic

For example, with cURL you can first log in as a DreamFactory admin and get a session token:

curl -i -k -3 -X POST "http://localhost:8080/api/v2/system/admin/session" -d '{ "email" : "[email protected]", "password" : "your_password" }' -H "Content-Type: application/json"

Then make a cURL call to the Edmunds API, like this:

curl -i -k -3 -X GET "http://localhost:8080/api/v2/edmunds/makes?state=new&year=2015&view=basic" -H "X-DreamFactory-Api-Key: <api key for the admin app in the apps tab>" -H "X-DreamFactory-Session-Token: <session token returned by the login api call above>"

DreamFactory combines the request URL from the client with the configured base URL for the service to generate the actual URL for the request. Everything after the service name, 'edmunds' in this case, is appended to the base URL to generate the final URL.

GET https://api.edmunds.com/api/vehicle/v2/makes?state=new&year=2015&view=basic&fmt=json&api_key=xxxxxxxxxxxxx

DreamFactory also appends the fmt and api_key parameters before sending the request on to the Edmunds API. This ensures that your API key or other sensitive information is never exposed to the client app. The response will be in JSON format. It has been shortened here for the sake of clarity.

{
    "makes": [
        {
            "id": 200002038,
            "name": "Acura",
            "niceName": "acura",
            "models": [
                {
                    "id": "Acura_ILX",
                    "name": "ILX",
                    "niceName": "ilx",
                    "years": [
                        {
                            "id": 200701415,
                            "year": 2015
                        }
                    ]
                },
                {
                    "id": "Acura_MDX",
                    "name": "MDX",
                    "niceName": "mdx",
                    "years": [
                        {
                            "id": 200698434,
                            "year": 2015
                        }
                    ]
                },
                {
                    "id": "Acura_RDX",
                    "name": "RDX",
                    "niceName": "rdx",
                    "years": [
                        {
                            "id": 200693511,
                            "year": 2015
                        }
                    ]
                }
            ]
        },
        ...
    ]
    "makesCount": 42
}

The result is returned back to the client. You also have the option to create server-side scripts to manipulate the request or response.