Composite key for REST API methods

Question

I'm looking for the best practices on RESTful API design for the following use case:

Domain Object Vehicle:

class Vehicle {
    private String vehicleType;
    private String colour;
    private String transmission;
    private String yearOfIssue;
}

An example object:

Vehicle = {vehicleType : 'Car', colour : 'Red', transmission : 'Automatic', yearOfIssue : '2008'};

In this domain model, there is no single field unique identifier (e.g. vehicleId), but rather all fields of the object together form the primary key (this constraint is there in the database layer).

We have no flexibility to alter this domain model to add a single field unique identifier.

So my question is as follows - If I want to add a simple REST API on top of this domain object that provides simple functionality to CREATE, UPDATE, DELETE and GET Vehicles, what is the best practice for the PATH endpoints for these methods?

Following the above example, if the domain model were to have a single field unique identifier vehicleId, then I can imagine the following endpoints:

GET /vehicles/:vehicleId
PUT /vehicles/:vehicleId
DELETE /vehicles/:vehicleId

I'm not aware of a pattern that exists similar to this for composite keys as:

GET /vehicles/:vehicleTypecolourtransmissionyearOfIssue
GET /vehicles/CarRedAutomatic2008

seems incorrect.

Any advice on a good pattern to follow for this use case would be greatly appreciated.

Thanks

Answer 1

As per general REST standards, each endpoint exposes a resource, and client can work on them with http verbs. In this example your resource is vehicle, and client is fetching data from server using GET. Ideally, each resource should be uniquely identified with a unique (single) key.

But your resource (vehicle) does not have a single value unique key, and it cannot be changed in the system! In this case you can still make the GET call with all required parameters to identify the resource, like any other standard http calls, like

GET /vehicles?type=Car&color=Red&transmission=Automatic&manufactureYear=2008

The technology/platform you are using, if that allows making custom routes for your method, you can create a custom route something like

new route("/vehicles/{type}/{color}/{transmission}/{manufactureYear}")

And call your service as

GET /vehicles/Car/Red/Automatic/2008

The good thing about this is, your uri becomes shorter. But on the other hand [1] For all methods/resources of this type, you'll have to create custom routes, and [2] this uri doesn't make much sense unless you have knowledge of the specific method and route.

Answer 2

In ASP.NET Core, I typically represent a composite key like this:

POST /vehicles/(car:red:automatic:2008)

or

POST /vehicles/(car|red|automatic|2008)

The framework has no problem mapping these to action parameters in the specified order.

[HttpPut("vehicles/({car}:{color}:{trans}:{year})")]
public async Task<IActionResult> Add(
    string car, string color, string trans, int year, [FromBody] Vehicle request)
{
    await Task.CompletedTask;

    return Ok();
}

Example request: PUT /vehicles/(Ford:Ranger:100% genuine:2000)

Answer 3

To be RESTful, you would need to create a single, unique identifier to augment your class.

class Vehicle {
    public int vechicleId { get; set; }
    public string vehicleType { get; set; }
    public string colour { get; set; }
    public string transmission { get; set; }
    public string yearOfIssue { get; set; }
}

Then you could access it using HTTP:Get http://mysite/vehicles/3842. However, you may not have access to the internal, unique identifier, especially when you seed or update the database. I've run across similar issues and to use the REST verbs I'll include an external identifier to make it easier for humans and external systems to access the records:

class Vehicle {
    public int vechicleId { get; set; }
    public string externalId { get; set; }
    public string vehicleType { get; set; }
    public string colour { get; set; }
    public string transmission { get; set; }
    public string yearOfIssue { get; set; }
}

Then the verb looks like: HTTP:Get http://mysite/vehicles/externalId/sedanbluemanual2015. You don't have to parse the URI as all that data should be in the body of the message, you just need to make sure that the string uniquely identifies the vehicle.

[HttpPut("externalId/{externalId}")]
public IActionResult PutVehicle([FromRoute] string externalId, [FromBody] JObject jObject)
{
    // See if the record exists already.
    var oldVehicle = (from v in vehicles
                       where vehicle.ExternalId == externalId
                       select v).FirstOrDefault();
    if (oldVehicle != null)
    {
        <insert new vehicle>
    }
    else
    {
        <update old vehicle>
    }