JSONAPI should the endpoint URL match exactly the `type` of a resource

Question

I am building a jsonapi for my website, and while looking at various frontend components I came across https://github.com/dixieio/redux-json-api/tree/master/docs Which seems to resolve the endpoint URL directly from the resource type

It is part of the spec/recommendations to have the endpoint resolved exactl by the resource type ? I remember reading comment explaining there isn't an actual type naming convention.

My API has several endpoints for the registration of different types of user

/registration/admin
/registration/customer
etc.

Those endpoint have different business logic associated, but they all return a user type object.

• Is this a bad design to have several endpoints returning the same resource type ?

• Should I make changes in my code to introduce additional type like registration/user ?

• Or should I submit a patch to the library so it accepts custom endpoint URLs ?

Answer 1

I can't address specifically the framework you're using, but you have complete freedom to choose what your HTTP resources represent. If, for example, customers can be corporate and have associated invoices and sales history, but admins are only ever individuals and cannot transact, you could make a strong case for keeping the resources seperate.

One thing you should try to avoid is allowing limitations of software dictate your URI structure. If I were creating this API, and had decided that customers and admins were different types of object, I would have the registration form resources live at /admins/new and /customers/new which would make POST requests to the collection resources at /admins and /customers. I would not have a /registration* at all.

To address your invividual questions:

1. I don't understand what you mean by ‘returning a resource type’ — are you talking about the representations returned in the responses, or how the back-end functions are creating and returning instances of a class?

2. I would not add an additional super-type for all kinds of user. Either have one collection per type, or one type for all.

3. If after considering all of the above and choosing URIs you want, your software cannot handle the structure you have chosen, there are three options:
   i) choose more capable software
   ii) create a mapping between the incoming URI and the URI handed to your software. Apache mod_rewrite can do this for you
   iii) as you suggest, make the software you are already using more capable

Choose the easiest option.