0

I'm struggling with a decision about how to design a web-API where I create new "things". We roughly follow the API guidelines of Zalando, which do provide a nice starting point for web-APIs (https://opensource.zalando.com/restful-api-guidelines/). But there's no guidance on how to handle creating new resources, which might have dependencies.

To provide a simple example, I have a beloved automotive example.

Assume the following API:

GET /vehicle - will get a list of vehicles
POST /vehicle - will create a new vehicle

The vehicle might look something like this

class Vehicle {
  VehicleType Type { get; set; }

}

enum VehicleType { // This enum is an example - it might as well be some complex type.
  eCar,
  Car,
  Truck
}

Now for the Post, I need to know about valid VehicleTypes.

Would I rather do:
GET /vehicle-type or
GET /vehicle/types or
GET /vehicle/dependencies/types or
GET /new-vehicle and include the dependencies?

Which approach is "well-known"? Are there other well known approaches?

New contributor
TGlatzer is a new contributor to this site. Take care in asking for clarification, commenting, and answering. Check out our Code of Conduct.
  • Vehicle types don't depend on Vehicle (it's just the opposite) so /vehicle-types seems reasonable to me. – Laiv May 15 at 9:35
  • If the vehicle types are unlikely to change and there are only some valid values, I prefer putting the list of valid values to the API documentation to creating a separated endpoint. – Hieu Le May 15 at 10:02
  • 1
    @HieuLe that leads to hardcode values on the client-side. New values might force you to deploy new versions of the client and this is important if we were speaking about mobile apps. – Laiv May 15 at 10:18
  • I agree. That is the reason I'll only hardcode these value if they are unlikely to change. In this use case, I think the list of supported vehicle types won't change frequently. – Hieu Le May 15 at 10:56
4

I think that types are not a dependency of Vehicle in this scenario. A vehicle type still exists without a vehicle but presumably, a vehicle cannot exist without a type?

GET /vehicle-type HTTP/1.1

Would be fine in my opinion.

  • Yes - the vehicle depends on the type - it's neccessary. So - essentially you'd go for a resource for every dependency of such an type or could you think of exceptions? – TGlatzer May 15 at 9:57
  • 4
    Look at these endpoints as lookups. If you want clients to get up-to-date values of vehicle-types then you have to provide an endpoint. Once on the client-side, you may cache the list of vehicle-types for a while (minutes, hours) or during the whole session. – Laiv May 15 at 10:14
  • ==@Laiv - cache the response! You shouldn't need to check for new values more often than once a day - surely clients can wait that long. Maybe even once a week. – Eric Stein May 15 at 13:46
  • Caches are evil. The shorter-living they are the better. If we were speaking about web apps, we could use the HTTP cache headers too. – Laiv May 16 at 6:45
2

There is no need to do a get at all.

The guidelines you quote require that you publish a schema for all your objects. This would include the enum eg (example from https://swagger.io/specification/#schemaObject):

"huntingSkill": {
            "type": "string",
            "description": "The measured skill for hunting",
            "default": "lazy",
            "enum": [
              "clueless",
              "lazy",
              "adventurous",
              "aggressive"
            ]
          }

So the enum will be encoded into the client along with the definition of Vehicle

  • Heh - you're right. The example I choose is somewhat short, it might not be an enum, but a pseudo enum like a group to be choosen from or any other dependency as well. So you are correct for REAL enums :) – TGlatzer May 15 at 15:46
  • surely other things are covered by their own resource? – Ewan May 15 at 15:56
  • That might or might not be. And I wanted to have input, how people handle dependencies, to be able to distill a best-practice. – TGlatzer May 15 at 16:56
  • Now just decide whether to deploy Swagger's endpoints on production is convenient or not and if you want to lock your solution to it. – Laiv May 16 at 6:48

Your Answer

TGlatzer is a new contributor. Be nice, and check out our Code of Conduct.

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.