search

DotNetHypermedia / DotNetHypermedia

Hal media type server side library for .NET
MIT License
14 stars 6 forks source link

initial commit #15

Open wis3guy opened 9 years ago

wis3guy commented 9 years ago

Attempted to setup a basic architecture that could work across frameworks and formats.

Intended as a discussion starter!

JakeGinnivan commented 9 years ago

This is good to have an alternate to start discussion.

What I was thinking is that instead of building an intermediate object our serialisers have a lookup which gives the hypermedia for a given model.

wis3guy commented 9 years ago

Well, my thought here is, that it is not just about hypermedia. In HAL, we recognise embedded resources, these have no place in collection+json. Likewise, 'search' has no place in HAL. So rather than abstracting these format specific features away (leaky), we make them first class citizens in the format specific library.

But you are right, it is something to discuss. I'm open for options ...

Ciao, Geoffrey

Geoffrey Braaf | +31655793290 Freelance .NET Software Architect & Passionate Developer | http://wis3guy.net Findsi: find-as-i | http://www.findsi.com

On Mon, Dec 1, 2014 at 11:54 AM, Jake Ginnivan notifications@github.com wrote:

This is good to have an alternate to start discussion.

What I was thinking is that instead of building an intermediate object our serialisers have a lookup which gives the hypermedia for a given model.

— Reply to this email directly or view it on GitHub https://github.com/DotNetHypermedia/DotNetHypermedia/pull/15#issuecomment-65048528 .

wis3guy commented 9 years ago

I realise that there are several involved people who feel that having an intermediate representation of a resource is not needed and perhaps feel that it just add more layers of abstraction. As i have some trouble grasping the underlying motivation i thought it would be wise to motivate my suggestion with more than just code. Again the record, this reflects my personal opinion and is posed here as a discussion starter.

Intermediate types enable what i dubbed IResourceConverter instances. These converters are developed by a consumer of our library and have a single responsibility: Convert a model into a resource and vice versa.

As a result:

I totally realize that this might cause consuming developers to have to write specific conversion code for each of the formats they want to support. Imho that is a valid tradeoff for gained flexibility. Realise that that is still better from what you would do today; Using a different library for each format, each incurring specific code to be written in a different way. At least we make the way you do it consistent (and hopefully simpler).

If we really wanted to, we can surely come up with a set of default converters that can do convention based conversion, without sacrificing flexibility and format specific features.

wis3guy commented 9 years ago

@JakeGinnivan, @andlju, @danbarua, @chrisaswain, @panmanphil, @glennblock, @jchannon, @AlexZeitler What are your thoughts?

panmanphil commented 9 years ago

Thanks for pushing this forward. My thoughts? I am still trying to formulate them but here is where I'm at for the moment. I'm not sure this project would gain a lot of support, but please realize I have a personal bias towards small focused libraries and away from larger, all encompassing frameworks. There was another project briefly discussed on the apicraft mailing list where they were trying to describe all the various formats in meta data and build transformations between them as I recall. I don't think it got a ton of traction and I don't think it is beyond a few resource types. I have the notion that most of these media types are unlikely to be with us for long, including HAL as it stands today, so putting a lot of effort into the existing formats could end up costing a lot of volunteer time for little adoption.

All that said, the notion that you separate the underlying data from the hypermedia components with a generic representation as described sounds good. Perhaps we could prove this out for the current library and plain json and see how we like it.

wis3guy commented 9 years ago

@panmanphil Thanx for your reply!

I respect your opinion, and partially agree to it, but i feel we are not on the same page regarding the intentions behind this project.

First, we are not trying to create a single large library. Rather, we are trying to develop a suite of libraries, based on one core library which you can selectively include into your projects. If you look at @JakeGinnivan's or my initial commits, we both envision you adding only:

In case you are working on a WebApi project and want HAL support.

We, or at least myself, are not trying to write conversions between different formats either. The proposed architecture/structure, in fact, dictates that you create format specific conversion from your domain models into resources. What we are trying to figure out, is: how much of the conversion code (developers write) could be reused across formats. Imho we strive to:

  1. Avoid lockdown into a single format, only because artifacts of the supported format trickles through into your controllers and potentially your BL, thus obstructing the support for multiple formats.
  2. Reduce the effort needed to support various hypermedia centric formats.

Regarding your remark that neither of the formats will be around for (very) long i tend to agree. At the same time, isn't that how the evolution of web technology has always evolved? I still remember SOAP being the silver bullet for all of our web services related problems. I'm quite sure some of the currently available formats will stick around for years to come. Other will slowly fade out and that's fine. Until they do, however, people do want to support them in their api. That is also why i feel that a suite to pick from, that contains libraries for multiple formats is a wise decision (not betting on a single horse for your product API).

glennblock commented 9 years ago

Hi @wis3guy, nice to see this. Added a few questions / comments inline.

One higher level question, can you give a description of what each of these contracts are for? Why do you need for example a resource serializer and a body serializer? What's the resource converter for, etc.

wis3guy commented 9 years ago

@glennblock Yes, i will work on better descriptions. Not sure if i should do that in code (comments) or a separate markdown file/comment/wiki.

glennblock commented 9 years ago

What does an IResourceObject buy? Why is it needed?

As to reuse, I have a concern that though on face value having those common abstractions seems nice, in practice it may not play out well and ends up with leaky abstractions. For example Links in CJ have additional elements like Prompt and Render which don't really make sense. Having a base link that has Uri and Href maybe makes sense. Possibly having some base classes / interfaces makes sense. Darrel Miller already has a nice library Tavis.Link (https://github.com/tavis-software/Tavis.Link) which includes support for Uri templates that might make sense to use.

Taking a dependency is going to depend a lot on factoring as well. I suggest there should be clear separation of client and sever pieces. In my CJ library I broke it into 3 layers, the OM for the Hypermedia docs, Client and Server.

On that note, one challenge on how to address client scenarios is the OWIN abstractions are only for server, there's no OWIN request/response for the client. There's HttpRequestMessage/HttpResponseMessage which are part of .NET, but I don't think RestSharp uses those.

High level, factoring is key here :-)

On Wed Dec 03 2014 at 9:47:16 AM Geoffrey Braaf notifications@github.com wrote:

@glennblock https://github.com/glennblock Yes, i will work on better descriptions. Not sure if i should do that in code (comments) or a separate markdown file/comment/wiki.

— Reply to this email directly or view it on GitHub https://github.com/DotNetHypermedia/DotNetHypermedia/pull/15#issuecomment-65454252 .

glennblock commented 9 years ago

@wis3guy I filed this to have a higher level discussion. I'd propose we create a gist or wiki page where we can iterate a bit on the contracts / the design. Not of the beers API, but the general contracts for writing "a" hypermedia implementation.

panmanphil commented 9 years ago

FWIW, this is all good stuff, but I'm buried in project work at the moment. I may have my head back above water next week, but the holiday season is upon us too, so I may be dark for a bit longer. It would seem I'm not the only one!

On Wed, Dec 3, 2014 at 4:30 PM, Glenn Block notifications@github.com wrote:

@wis3guy https://github.com/wis3guy I filed this to have a higher level discussion. I'd propose we create a gist or wiki page where we can iterate a bit on the contracts / the design. Not of the beers API, but the general contracts for writing "a" hypermedia implementation.

— Reply to this email directly or view it on GitHub https://github.com/DotNetHypermedia/DotNetHypermedia/pull/15#issuecomment-65503449 .

jchannon commented 9 years ago

No I'm flat out too

JakeGinnivan commented 9 years ago

Ditto, hopefully when we get into the new year a few of us can start it moving again