ASP.Net Web API architecture

[betim]

Hi,

I just wanted to know your opinion guys about organizing an API in Microsoft web stack platform.

What about "traveling" data back-and-forth from SQL Server (as database) to the api.

What technologies/methods/products you'll use to do that architecture (EF, Automapper, etc)?

br

b

[Glenn Block]

In general APIs should not leak your implementation details as they are two separate concerns. The key to designing evolvable APIs is to keep those two concerns clearly separated.

As to designing an API that is backed by a database/EF there are several different ways to achieve persistance / retrieval within Web API.

1. You could look at the new support for OData (in preview) that was added. The OData infrastructure makes it easy to expose an API that is basically based by a model which could be bound to a database. 

2. ASP.NET Web API integrates with EF / EF Code first. Using EF Code first you can easily create an API where the resources are backed by entities in EF. The EF support also works with EF migrations, thus it will generate a database for you on the fly and update the schema when you make model changes.

As far as mapping technologies, you are free to use whatever you choose with Automapper being a fine choice. Your API controllers are your playground so it's really up to you.

b

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Kevin Swiber]

Some .NET-specific info:  If you're on the latest version of the .NET Framework, look at using http://www.asp.net/web-api.  I've done a lot on top of ASP.NET MVC prior to Web API's availability.  One lesson I've learned: do your best to avoid mapping.  Query fields from a database or use denormalized read models. Mapping gets out of hand very quickly.  If necessary, Automapper is very helpful.  It eliminates left-right coding.

Regarding how to build an architecture for this, I think there are a lot of principles here that are platform agnostic.  I apologize if this gets a little verbose as I nerd out for a minute.

Model Separation: As use case complexity increases, the benefits of model separation increase.  Logically, these are all different representations: data model, domain model, application model, reporting model.  While this may be true, it might not make sense to separate all these in code if your use cases are very simple (CRUD-ish, for instance).  The most complex use cases will use all of the above.

The following represents a growth path as use case complexity increases.

API Over Data Model: If you're looking for an API over data, check out OData[1], as Glenn suggested.  An alternative that I promote from time to time is Collection+JSON[2].  OData has good support on the .NET Framework.  I'm not sure about Collection+JSON.  This is great when there is little to no behavior happening behind the scenes and you really need full-featured querying with CRUD.

API Over Domain Model: Designs in this arena may utilize some kind of ORM (Entity Framework, NHibernate, etc.) to hydrate "business"-layer objects that contain behavior specific to the problem domain of your application.  Look to Domain Driven Design[3] for good pointers here.  There's a step up here when your complexity starts to grow.  It's common to start separating how reads are handled from writes.  CQRS[4] provides lots of good guidance in this space.  Without CQRS, an API will often use property getters of the Domain Model to build API responses.  This is already the start of a leak in your Domain Model, which may lead to...

API Over Application Model: It may make sense to derive an Application Model from a Domain Model.  When resources are modified in your API, the changes typically route through the Domain Model.  When resource representations are fetched, they may be reading from a denormalized data store (document databases start working really well here) that has pre-populated application-specific models to serve through your API.

API Over Reporting Model: This is almost a parallel evolution with the the API Over Application Model concept.  The model being served might be coming from denormalized data.  This is typically read-only and may look more like API Over Data Model in implementation.  Complex analytics over this is a whole different beast.

Every question regarding design complexity comes back to... "It depends on your use cases."  Every step of architectural complexity comes at a price.  Make sure to always do at least some cost-benefit analysis before heading down one of these rabbit holes.  Good luck!  :)

[1] http://www.odata.org/

[2] http://amundsen.com/media-types/collection/

[3] http://domaindrivendesign.org/

[4] http://cqrs.wordpress.com/

-- 

Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[betim]

Glenn so happy you're here!

Maybe, was my fault I was to short on explanation, and I'm misunderstood a little bit.

My scenario is:

Planning to use Azure, so I'll have SQL Server on Azure.

As ORM is understandable I'll use EF (Code First of course).

But at this point I saw different approaches like, doing "service models" and exposing them,

using automapper for cases when you have same structure. using repositories and other techniques, and finally expose data through web api.

You were resting a lot lately :D, so, I'd like to see your approach please?

[Glenn Block]

Thanks Betim, good to be here.

I prefer to use media type model approach and not necessarily an auto mapping technology. That is when I start to think about designing an API I start from the client and think about what they will consume in order to interact with my application. I then create what I've been calling a Media Type Model, i.e. a set of classes that are specifically designed to carry the data necessary to create that media type representation. My API then becomes a thin layer which calls to services in my system retrieving the data necessary to populate that media type model which is then returned and written out using a formatter in web api. Now the media type model could be something general purpose for example a HAL or SIren formatter or it could be something specifically designed for my app.

Also when I say "media type" i don't necessarily mean it has been registered with IANA>. To illustrate what I mean, if you check out this post: http://codebetter.com/glennblock/2012/01/08/hypermedia-and-web-api-design-brain-dump-and-samples/ you will see an example for a contacts "media type" that includes hypermedia affordances. No this is not a real system, but it could be. If you look at the representation, you'll see that it is very tailored to the application. There's data within that comes from the backend, but it is then populated into a model which is then returned to the formatter.

That's my preferred approach, but it really depends on the system. You might think it is overkill, but I am also not saying you MUST do it :-) Also HAL seems to be getting a lot of traction these days so using HAL might work for your needs.

[Pat Cappelaere]

Glenn,

You can do the same thing without defining a custom media type.  This adds a level of complexity for no value added.

Your application and its customers will still work the same way :)

If we had to interface to many … many services that way… it would not scale.  Too much out-of-band information would be necessary prior to connecting.

Scalability happens with good service discovery.  If you have discovery, do you think that custom media-type would still be necessary ?

So I am really not sure that this is a good pattern.

Pat.

[Glenn Block]

Pat

I think you are misunderstanding what I mean.

I put "media type" in quotes and said I am not saying registered with IANA for that reason. I should have added that I am  not suggesting it has to appear as a different media type in the content type. What I am saying is you come up with a semantically rich messages format. 

I really like the Profile work that Eric Dret is driving which gives the ability to communicate to the client the specification / "media type" while still be able to return a content-type of say "application/json".

I also equally fine with using an existing media type like "application/hal+json" as I mentioned.

[Glenn Block]

I disagree btw that it adds no value, but you are welcome to your opinion. I am not saying it's always necessary but that is a very different thing than if it can add value.

Does having application/pdf, application/vcard and application/svg add no value?

On Tue, Sep 4, 2012 at 8:07 PM, Pat Cappelaere <cappe...@gmail.com> wrote:

[Glenn Block]

"If we had to interface to many … many services that way… it would not scale.  Too much out-of-band information would be necessary prior to connecting.

Scalability happens with good service discovery.  If you have discovery, do you think that custom media-type would still be necessary ?"

Custom media types are not out of band if they are registered with IANA. The media type is completely discoverable. I am not sure what  you mean there.

It's when you DON'T have a registered media type like an arbitrary application/myapp that it's not discoverable. The profile header however is a nice middle way.

That being said not every system is open like that. If you have a really broad set of client consumers the discoverability is really important. If however you are more of a closed system where you are in control of both sides it does not matter.

On Tue, Sep 4, 2012 at 8:07 PM, Pat Cappelaere <cappe...@gmail.com> wrote:

[Pat Cappelaere]

Glenn,

Thanks for the discussion.  I was trying to get this going here :)

My point is that: Major media types have value (application/pdf, application/json…)

but custom media types have little or no value (or negative value as it makes the system more complicated)

Custom media types would be defined as application/vnd.example.com+json (or equivalent)

Now if you use a profile or point to a schema, then it makes more sense

example:

application/json; describedby="http://example.com/schema.json"

Then you get a semantically rich message set that is documented in a schema, available online and discoverable.

That's the kind of discovery I am talking about.  No out-of-band information is required.

which takes us to the next question: :)

Would you really need application/hal+json in this case?

Probably not. :)

Pat.

[Glenn Block]

OK cool. It was good that you prodded because I wasn't being as explicit as I should be about what I meant :-)

"My point is that: Major media types have value (application/pdf, application/json…)

but custom media types have little or no value (or negative value as it makes the system more complicated)"

Well I think they provide some value, but they are also harder to consume. Though you can also support both, meaning you support application/json or application/foo depending on what the client supports.

I think mileage may vary here, BUT I do get your point.

"which takes us to the next question: :)

Would you really need application/hal+json in this case?"

Well HAL explorer would be happy if it knows you are HAL. I mean you could extend the same argument to PDF then. HAL aims to be a general purpose broad type. Thus is makes sense that HAL clients will pop up / to make it a standard media type IMO.

[Pat Cappelaere]

Glenn,

If you have a good service discovery, then an API explorer is a no brainer.  It would actually comes free.

Your service ought to be mandated to point to it (to help newbees). [look at iodocs or equivalent… or it may be a HAL explorer if you happen to use HAL]

Any other client could also leverage that info… This would make everyone's life simpler :)

Pat.