RESTFul media type inheritance - rest

Question

I'm completely new to REST. I helped to implement something that was called REST at work but it breaks so many of the rules that it's hard to qualify it as REST. I want to follow the HATEOAS guideline and the remaining question I have is regarding documentation of media types and their specification. Namely when one media type is really an extension of another.
For example, I've decided on 'application/hal+json' for the base media type. Everything that a user would receive is going to be a HAL blob with some added fields. I don't want to call my media types just 'application/hal+json', it seems to me more information should be available than that, but I want it to be clear that this is what they are in addition to the extra fields that are my data. Furthermore my system is going to end up having some of these fields inherited and such in both the request (which won't be HAL blobs) and response formats. A generic "User" type might have just a user id and name for example while an extension like "Student" or "Teacher" will have different additional fields.
Does it make sense to represent this extension somewhere in the media type itself? Do people generally document the relationship in their HATEOAS documentation links? If so, what's the general trend here? I want my API to be easy to use and thus figure it should follow norms that are available.

Answer 1

Couple of things i'd like to point out about your move to a true RESTful architecture.
First, RESTful APIs must perform content negotiation. To say your base type is hal+json is seems strange. It sounds like you want to have types like parent+hal+json or maybe hal+json;type=parent. This would mean your client would have to understand these types specifically...and this would be not very RESTful because it's just a local implementation. This is fine in the real world..you can do this...almost everyone does stuff like this.
To be true RESTful api you'd have to offer similar support for other content types...that could get messy.
Now specifically to HAL, there's two things available to you so that your client can "discover" what data types they are getting back. One is CURIEs and the other is Profiles https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06#section-5.6 I think Profiles is more what you're after here as it allows you to document conventions and constraints for the resource that will be retrieved.
But don't count out CURIE's either. There's lots of defined semantics out there already. Your model might fit one of http://schema.org sets and then you can just use their link relationships and the client should know what's going on.
If you really want a lot of control on the semantics of your resources...you may want to look at http://json-ld.org/ with it's #context concept would be a good reference.
In my opinion this is an area where the examples are very thin, especially for HAL. I've yet to seen a client smart enough to parse and care about semantics at run time. What i think is important is when someone is building the client that info is available they can figure out that a Student is a Person. One day the thing building the clients will be client generator code and it'll use that info to build a nice client side object model for you.
TL;DR if you stick with HAL use CURIEs and Profiles to get what you want.

Answer 2

This question is an extremely open ended discussion and it really depends on how different engineers interpret REST standards and best practices. Nonetheless, As a fellow software engineer with enough experience with REST services development (and faced the same questions professionally as you did), I would add my inputs here.
REST service development rules are heavily dependent on the url definitions. It's very important that you expose your apis in such a way that your clients can understand exactly what's happening per api just by looking at the url definition.
With that being said, different clients (and for that matter different engineers) view the best practices differently. For example, if you are trying to search a User by email, there are atleast two approaches
1) GET /users/emails/{email} // A client can interpret this as
"getting a user by email"
2) GET /users?email={email} // A client can interpret this as
"searching a user by email" because of query param
3) GET /users/email={email} // This can be interpreted just as # 1
It depends on the developer how they want to expose this api and how they document it for the clients. All the approaches are correct in different perspectives.
Now going specific to your questions. Here's what my approach would look like in terms of "User", "Student" and "Teacher".
I look at each of these 3 as separate resources? Why? because they are separate types even though 2 of them are extended from the 3rd one. Now how would my apis look like for these?
For Student:
1) Retrieving a list of students : GET /students
2) Retrieving a Student with id: GET /students/{id}
3) Creating a Student : POST /students
4) Updating a student : PUT /students/{id}
5) Delete a student: DELETE /students/{id}
6) Search a student: GET
/students?{whateverQueryParamsYouWantForSearch}
The same will be applied for Teacher as well.
Now here's for User.
1) GET /users : Retrieving list of all the users (Students and
Teachers)
2) GET /users?type={type} : Here's the kicker. You can specify the
type to be student OR teacher and you will return the data of specific
type (properly documented ofcourse)
3) POST /users?type={type} : Create a specific TYPE of user
(student or teacher)
.. And so on.
The main difference is .. the apis with root url /users can be used for BOTH types of users (Provided the type is always specified and documented to the clients). While the Student and Teacher apis are specific to those types.
My money has always been on specific types while generic types for searching (meaning for searching both types of users .. use /users?params). It's the most easy way for the clients to understand what's going on. Even documenting them is much easier.
Finally talking about HATEOAS. Yes, it's a part of the standards and the best practice is to ALWAYS provide a url/link to the resource you are returning or if your return object is complex and contains other resources which might contain resources who might themselves be exposed through apis. For example,
/users?type=student&email=abc#abc.com
will return all users with that email and it's better to follow HATEOAS here and provide a url to each returned user such that the url looks like : /students/{id}. This is how we have normally handled HATEOAS
That is all I have to add. As I said earlier, its a very open ended discussion. Each engineer interprets the standards differently and there is no ONE WAY to handle all usecases. There are some base rules and the clients and other developers will applaud you if you follow them :)