API Reference

Based on simple REST principles, the CAR FOR YOU REST API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The base address of the API is https://api.carforyou.ch. To access dealer’s data, such as listings, images and equipment, an application must get access permissions. Authentication and authorization is performed via the CAR FOR YOU Auth Service.

Quickstart

If you already received the credentials (Client ID and Client Secret) from the CAR FOR YOU Engineering Team:

  1. Obtain an access token from the Auth Service:

curl -X POST -d 'client_id=<partner_client_id>' -d 'client_secret=<partner_client_secret>' -d 'grant_type=client_credentials' https://auth.carforyou.ch/auth/realms/carforyou/protocol/openid-connect/token

{
  "access_token": "eyJhbG...qMEtAw",
  "expires_in": 300,
  "token_type": "Bearer"
}   
  1. Use the access token to access the API:

curl -X GET -H 'Authorization: Bearer eyJhbG...qMEtAw' https://api.carforyou.ch/v1/dealers

{
  "content": [
    {
      "id": 1923,
      "name": "Global Cars Limited - Branch 1"
    },
    {
      "id": 1925,
      "name": "Global Cars Limited - Branch 2"
    }
  ],
  "first": true,
  "last": true,
  "numberOfElements": 2,
  "number": 0,
  "size": 25,
  "totalElements": 2,
  "totalPages": 1
}   

After you successfully authenticate and make an API request, you’re ready to begin integrating CAR FOR YOU.

Make sure you:

Authentication & Authorization

Authentication and authorization is performed via the Auth Service, which is built on standard protocols, OpenID Connect and OAuth 2.0, enabling integrations and allowing fast growth of the CAR FOR YOU universe.

Most of the requests to the API require authentication. You need to obtain an access token first, and send it for each API request in the request header (Authorization: Bearer <access_token>), as long as the token is valid. Once the token expires or gets invalidated, make sure to obtain a new one following the same procedure.

Server-to-Server

The Client Credentials Flow is used in server-to-server authentication. The Client ID and Client Secret will be provided to the partners by the Engineering Team.

Note that per OpenID Connect specification the Token Endpoint accepts the HTTP POST method and the Form Serialization (x-www-form-urlencoded) content type.

The token endpoint address is https://auth.carforyou.ch/auth/realms/carforyou/protocol/openid-connect/token.

Full example:

curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=<partner_client_id>' -d 'client_secret=<partner_client_secret>' -d 'grant_type=client_credentials' https://auth.carforyou.ch/auth/realms/carforyou/protocol/openid-connect/token

{
  "access_token": "eyJhbG...qMEtAw",
  "expires_in": 300,
  "token_type": "Bearer"
}   

Other Notes

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests that require authentication will fail if an invalid or expired access token is provided.

Your API credentials carry many privileges, so be sure to keep them secure! Do not share your credentials in publicly accessible areas such as GitHub, client-side code, and so forth.

Errors

CAR FOR YOU uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an update failed due to business logic violation, etc.). Codes in the 5xx range indicate an error with CAR FOR YOU’s servers (these are rare).

Some 4xx errors could be handled programmatically.

Status Code Description
200 OK - The request has succeeded. The client can read the result of the request in the body and/or the headers of the response.
201 Created - The request has been fulfilled and resulted in a new resource being created.
202 Accepted - The request has been accepted for processing, but the processing has not been completed.
204 No Content - The request has succeeded but returns no message body.
400 Bad Request - The request could not be understood, often due to missing a required parameter. The message body will contain more information.
401 Unauthorized - No valid user authentication (access token) provided.
403 Forbidden - The authenticated user doesn’t have required permissions to perform the request.
404 Not Found - The requested resource could not be found.
422 Unprocessable Entity - The request is valid, but the business rules validations failed. The message body will contain more information.
429 Too Many Requests - Rate limiting has been applied.
500, 502, 503, 504 Server Errors - Something went wrong on CAR FOR YOU’s end. These errors are rare.

Response Schema

The API uses two different formats to describe an error:

  • Authentication Error Object
  • Regular Error Object

Authentication Error Object

This error type is specific to the Auth Service. Whenever the application makes requests related to authentication or authorization, such as retrieving an access token or refreshing an access token, the error response follows RFC 6749 on the OAuth 2.0 Authorization Framework.

Key Value Type Value Description
error string A high level description of the error as specified in RFC 6749.
error_description string A more detailed description of the error as specified in RFC 6749.

An example of a failing request to obtain an access token:

curl -X POST -d 'client_id=<partner_client_id>' -d 'client_secret=wrong-secret' -d 'grant_type=client_credentials' https://auth.carforyou.ch/auth/realms/carforyou/protocol/openid-connect/token

{
  "error": "unauthorized_client",
  "error_description": "Invalid client secret"
}

Regular Error Object

This error type is specific to the API. Apart from the response code, unsuccessful responses for 400 Bad Request and 422 Unprocessable Entity return a JSON object containing the following information:

Key Value Type Value Description
message string A high level description of the error.
description string A more detailed description of the error.

An example of a failing request to create a listing:

curl -X POST -H 'Authorization: Bearer eyJhbG...qMEtAw' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{}' https://api.carforyou.ch/v1/dealers/1923/listings

{
  "message": "validation.not-valid",
  "description": "Invalid input provided for one or more fields"
}   

Date/Time Format

All dates in the API use UTC and are strings in the ISO 8601 format:

  • date: 2018-10-18
  • date-time: 2020-05-15T15:50:38Z

Pagination

Some endpoints support a way of paging the dataset, taking a page and size as query parameters:

curl https://api.carforyou.ch/v1/dealers/1234/listings?page=2&size=10

In this example, in a list of 50 (totalElements) listings of the specified dealer: skip the first two pages (first 20 listings on pages 0 and 1) and retrieve the next 10 (size) listings.

Note: The page numbering is zero-based. Check the specification for the specific endpoint and verify the default values.

Free Text Input

All free text input fields are scanned and sanitized upon submission, before saving the data in the CAR FOR YOU database. Not allowed content will be stripped off automatically.

Some fields, like the Listing’s description and externalNote, may be formatted by HTML tags. The list of supported tags includes <b> (bold), <br> (line break), <i> (italic), <u> (underlined), <ol>/<ul> (ordered/unordered list), <li> (list item) and few more. A line break can also be represented by a newline character \n.

Rate Limiting

Rate Limiting enables the API to share access bandwidth to its resources equally across all users and applications.

Note: If the API returns status code 429, it means that you have sent too many requests. When this happens, wait some time before you try your request again.

Versioning

CAR FOR YOU considers the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
  • Adding new enum values.
  • Your client should gracefully handle unfamiliar enum values.

Swagger UI & OpenAPI Specification