API Architecture? (Need Resources)

[AR]

Hi does anyone know any good reads sharing their API designs? Links to your github repositories are also appreciated. I am after code design.

How you organize your actions, tasks, models, events, policies, exceptions, contracts, traits, providers, tests, migrations, seeders, factories, criteria, repositories, routes, controller, requests, transformers, formatters, commands, domain services, infrastructure, helpers, extensions, middlewares etc.

thank you API Craft

[André Tavares]

Hi!

Here's my take on an E-Commerce RESTful API :) --> https://github.com/yoonic/atlas

[mca]

AR:

not sure exactly what you're after but i'll share my internal code model for writing shared (e.g. HTTP) services (micro- and regular-sized). I will warn you that none of what appears below easily fits into the typical MVC/MVVM/etc patterns most frameworks are built to support. However, i find this works well, hides complexity behind static interfaces, scales well, and is easy to code/maintain.

FWIW, i architect my services as follows:

DATA MODEL

1) i implement a data storage layer that has a single interface. i do this so that i can assure a non-changing interface while i add new data tables, documents, queries, etc. even change storage from relational to NoSQL, etc. w/o ever breaking anyone else's code

OBJECT MODEL

2) i implement an internal object model to represent the domain (DDD-style, if that suits you). this domain model is usually an "object" (task, user, etc.) that accepts messages/actions and args. so the object has a very simple interface, too. BTW - that object MAY access data storage (see #1) above.

RESOURCE MODEL

3) i implement an external HTTP interface (basically resources) that, by the very nature of HTTP, accepts a single message on a port and then processes that request into a response using the internal object model from #2.

REPRESENTATION MODEL

4) finally, the responses from the HTTP interface ALWAYS go through a representor module to convert the internal object tree into a standardized messasge (HTML, Atom, HAL, Siren, Cj, UBER, CSV, etc.). this makes sure that, no matter how the data, object, or resource models change, the service responses will ALWAYS be in a well-known format that the client can deal with.

I cover this in a talk from last year (the pattern above is in the middle of the deck)[1]

Cheers.

[1] http://amundsen.com/talks/2015-11-caworld-dorr/index.html

mca

Mike Amundsen

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[AR]

Hi thanks guys I will check what you have posted here. These are very helpful

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.

[Chris Mullins]

This sounds like a homework assignment. :) 

What do you think is a good way to organize and approach API design? 

Cheers,

Chris

[Kevin Swiber]

As in... "How should I structure my code files?"

Most platforms/frameworks have their own idioms and conventions to follow.  I usually follow suit.

Mike A's response outlines my thinking on the various models in play, though I've used different words in the past.  Here's an old post of mine that speaks to different models: https://groups.google.com/d/msg/api-craft/rGPS2uwG5gs/Bx-8NCo9SekJ.

Sticking with Mike's language for the sake of continuity in this thread, the models that may impact your API design are the Resource and Representation models.  I see various components in your list that might suggest you're using Domain Driven Design (DDD) and Command-Query Responsibility Segregation (CQRS).  The DDD bits would live in your Object Model.  It's tempting with CQRS to expose commands and events through the Resource Model.  I often advise against this.  I know it's tempting.  But the consumption story is easier to tell when using a Resource Model that's very specific to the _application_ concerns.  CQRS commands and events are often directly coupled to an Object Model (Domain Model in DDD).  Getting sloppy here creates a weird mess to maintain down the road.

Good luck!

Cheerio,

Kevin

--

[API Dev]

Assuming the question is about understanding how to implement API's in general, looking at some of the talks at various conferences including apidays, nordic apis etc would be helpful. It would ideal to get a book/video that talks in detail on each of the topics mentioned in the original post. I would love to have a look at it.

[Owen Rubel]

API as architecture is literally all I do. I have given talks on this at SpringOne, API World, API Days, Univ of Wash, Univ of Calif - Berkeley and been asked to speak to dev teams at VMWare R&D, Mashery, Apple, Amazon and others.

If you want to know how to do modern API architecture, I would point you to one of my talks: infoq.com/author/Owen-Rubel

or one of my slides: https://www.slideshare.net/bobdobbes

These will provide enough information to get you started.