Can the URL be plural but `type` be singular?

1

So I see that in the spec the resource name is plural for both the URL and type. But is it Ok to have the URL plural and type singular? Ex: http://example.com/articles returns resources of type article

While the following is in the spec, it doesn’t clarify if the URL and type need to match. But maybe I’m missing that language elsewhere.?.

Note: This spec is agnostic about inflection rules, so the value of type can be either plural or singular. However, the same value should be used consistently throughout an implementation.

2

I would say it might not be strictly forbidden as far as I can tell, but it is not a good idea. You’re bringing confusion for no benefits in exchange.

3

If you only ever have one of that resource, then singular makes a lot of sense. E.i profile for the user’s profile, since he doesn’t have multiple profiles.

But use it sparingly and deliberately.

4

But use it sparingly and deliberately.

Otherwise stick with plural form?? Sounds like that’s the defacto standard with JSON:API.

FWIW, I’ll be working with ember-data, which does do pluralization. Customizing Adapters - EmberData - Ember Guides

5

You do you. If you’re the only consumer of your api, then it really doesn’t matter what solution you choose, as long as it makes your life easier.

6

Yes, URL could be plural, but type singular.

More to say, they might be completely different words. For example GET /vehicles endpoint might return resources of type Car, Aircraft, Train, Ship, and so on.

In my APIs I’m always using singular types.

7

@a-komarev I could see a relationship returning different types like that, but I’m not sure that a “root” resource should do that. It would be difficult to document and wouldn’t you need a resource URL for each of those types.?.

8

@panman82 you might have endpoint for each type of resource or have endpoint which will have many subtypes. For example GET /vehicles will return CarVehicle, AircraftVehicle, TrainVehicle, ShipVehicle.

But in reality your endpoint could have non-human friendly name GET /a1b2c3 and it will be fine. There is no strict limitations for the URI names. To be honest many JSON:API libraries ties types with endpoints, but I think it’s a question of time.

I highly recommend you to read @michaelhibay set of articles about Hypermedia API. For your question there is an stop worrying about your URI patterns article in it.