Organizing and Naming Serializers/Deserializers

[smizell]

I'm currently on the tail end of having a usable version of the hypermedia resource library for Python. Once it's ready, I want to work on a couple of serializer/deserializer objects. I have several questions around this.

1. What should these be called? I have called them adapters recently, and translators in the past. I could see a more common name like plugins as well. Does anyone have any thoughts on a simple name to call these?
2. What should we call the methods for adding these to the hypermedia resource object? I've called it register in the past. I could see other names like add or load being used. Any thoughts on a name here?
3. What is the canonical interface to these adapters/plugins/etc.? In the past, I've had a media type name (e.g. application/hal+json), a parser (to deserialize), and a builder (to serialize). Better names here? Anything to add?
4. Should these adapters/plugins/etc. be referenced via the registered media type name? Or a shorter, agreed-upon name? In other words, application/hal+json vs. just hal+json?
5. How should these adapters/plugins/etc. be organized? Should they be within the main hypermedia resource repository for each language? Should they have their own repositories?
6. Related to the last question, should the main hypermedia resource object register all of the major adapters/plugins/etc. by default? Or should we rely on the user of the library to register them?

Thanks!

[smizell]

I've implemented all of these in the Python library. Here's what I did.

1. I called them adapters.
2. I've used add
3. I've uesd parse and build
4. I've used the registered media type (e.g. application/hal+json)
5. I've kept them all in the same repo
6. I registered the major ones upon import

I wanted to get something working, so I just went ahead with what I had. If we decided to name these differently, I'll gladly change any these!

[zdne]

👍

I agree on every point. The only one I am not sure is

6 Related to the last question, should the main hypermedia resource object register all of the major adapters/plugins/etc. by default? Or should we rely on the user of the library to register them?

I would expect the Hypermedia Resource work out-of-the-box that is – using all means possible parse response into Hypermedia Resource objects – if that means the adapter whether that means an adapter has to be registered at start or on-demand is not my concern. I would not ask user to register adapters unless he or she is using a custom one...

[smizell]

I agree with you on that, and that's the direction I took. I do have a "browser" adapter for building HTML, but I'm not including that by default at this point.

Right now, if the user imports the hypermedia library, it gets all of the supported formats by default.

[MatthewReinbold]

Even though some of us aren't quick-to-the-draw, that doesn't mean we aren't following the conversation. ;) Thanks for all your work so far! Hopefully, I'll get a chance to grab this and given it a try in the next few days. With luck that will help clarify some of these concepts that your driving at.

[glennblock]

For CJ I used readers and writers, parser works. I am not thrilled with just adapter because it is so generic, the adapter does have a more specific purpose. Even though it is a bit verbose I'd almost say it's a mediaTypeParser/mediaTypeWriter or maybe mediaTypeAdapter.

[fosrias]

@glennblock I lean in your direction w/r to how we might name these. @smizell's adapter is a little generic and serializer/deserializer is more technical than having semantic richness in the domain of these things.

[smizell]

I'm not attached to the name adapter either, but used it for lack of a better term at the time. Also, just a thought, but in addition to media type adapters, there may need to be adapters for message headers.

[glennblock]

I forget to mention that it is great to see the progress @smizell.

As for the naming, I am not super attached either, I just think adapter is so vague.

Another idea is to use content, i.e. contentParser, contentGenerator as at the end of the day you are reading or writing from the content.