Tag: REST

REST Primer for F&I

I have worked with more than a few APIs, both “F” and “I” – pretty much all of the product APIs, plus the original open standard for credit applications – and I write about them occasionally.  See here, here, and here.  Mostly these have been SOAP, but REST is the standard for a growing community of digital retail players.

The first thing you need to know about REST is that it’s not synonymous with JSON.  If you get this wrong, you can produce a really bad API.  I saw one once, where the developers had simply converted all their old XML payloads to JSON.  You could tell because every call was a POST, even the rate requests.

Why is JavaScript more successful on the Web than Java? It certainly isn’t because of its technical quality as a language – Roy Fielding

The key to REST, as you can read in Roy Fielding’s dissertation, is making appropriate use of the Web’s native HTTP environment.  Practically, this means knowing a little bit about HTTP and how to use its commands, URLs, parameters, and headers.  For a concise guide, see The REST API Design Handbook by George Reese.

Philosophically, it means thinking about your API in terms of resources and not services.  This is completely different from SOAP APIs, which are called web services.  For example:

  • GET rates from a product provider, but
  • POST a new contract, and then
  • PUT status codes on the contract to void or remit

Fielding’s achievement was not only to define the REST style, but to derive the style from a specific set of requirements: stateless, client-server, code on demand, etc.  If you have ever wondered why JavaScript has become so popular, it is because JavaScript satisfies the code on demand requirement.

When you build a RESTful API, you should never break existing client code. Really, never. You don’t deprecate – George Reese

The URL in a REST call looks like a path, so you can do groovy things like:

  • GET /rates/{dealer} – gets all applicable rates for this dealer
  • GET /rates/{dealer}/{product} – gets only one product
  • GET /rates/{dealer}/{product}/GOLD – gets only the Gold coverage
  • GET /text/{dealer}/{product}/GOLD – gets the rich text description for Gold

For some live examples you can run right now, check out the NHTSA Vehicle API.  It has many handy methods like:

  • /vehicles/DecodeVin/{VIN}
  • /vehicles/DecodeVinExtended/{VIN}
  • /vehicles/GetAllMakes
  • /vehicles/GetEquipmentPlantCodes/{Year}

Note that you are making the request with straight HTTP and a query string, and you can have the response as JSON, CSV, or XML.  The NHTSA site will also show you the headers, the raw data, and formatted data.  Your tax dollars at work.  You should also check out the Edmunds API, VinSolutions, and Fortellis.

  • //api.edmunds.com/api/vehicle/v2/vins/{VIN}
  • //api.vinsolutions.com/leads/id/{LeadId}
  • //api.fortellis.io/vehicles/reference/v4/vehicle-specifications/vins/{VIN}

These are all examples you can emulate if you’re just getting started.  In particular, I recommend studying how they handle authentication and versioning.  Note how they’re organized around resources and, if you have an OO mindset, think of your objects first.  You will also want to look at platform tools like Swagger and MuleSoft.