Creating Our First API

[Chad Alderson]

Hi there - 

We are the creators of http://www.bettingbad.com - an experiment we launched mid July to predict the season finale of Breaking Bad. Think of it as fantasy sports for TV. You can learn more about how it works here: https://www.youtube.com/watch?v=LO2aC_UMXMo. We got some decent press: http://press.bettingbad.com/coverage and about 8K people playing within 30 days of launch. Based on this success we've decided to expand the scope. Part of the strategy relies on a well crafted and documented API. 

We are wrapping up requirements and UX and are almost ready to start looking for a few engineers to help us out on the platform aspect of the project. 

My questions:

1. Is a requirements document and detailed UX for both the consumer facing experience and admin screens enough to scope work from? My intuition says yes because the data model is implied (mostly) in the spec and UX. 
   
2. There are so many options in terms of data exchange tech (SOAP, REST, JSON, etc.) assuming you were targeting iOS devices but later web and Android, which one would you go with?
   
3. Is it realistic to be building the client in parallel to the API to support it? I'm hoping so as I'm assuming the actual app will be the use-case/proving ground for the API on which it relies.
4. Is it typical that the same team of people who build the API be responsible for the docs, or should I consider contracting a tech writer for this? We don't plan to have a public API till later so I'm hoping we can get by on our home-grown docs since our own teams will be the ones consuming them for the short to mid-term.
   
5. In general, any advice or thoughts on getting started? 
   

Finally - I'm looking to contract this part of work out so if anyone is interested please feel free to hit me up at: chad <<AT>> spark6.com.

Thanks in advance!

Chad

[mca]

first, cool project!

here's my quick comments on your Qs:

1. Is a requirements document and detailed UX for both the consumer facing experience and admin screens enough to scope work from? My intuition says yes because the data model is implied (mostly) in the spec and UX. 
   

1. ***
   as long as you design you API as use-case driven (GET /admin-dashboard) and not object-driven (GET /users/) your UX and screen shots SHOULD be documentation enough to build the first pass at a complete API set. My advice is to commit to use-case approach and stick to it. mixing use-case and object-style will create a mess you likely can't sort out in time. 
   ***

1. There are so many options in terms of data exchange tech (SOAP, REST, JSON, etc.) assuming you were targeting iOS devices but later web and Android, which one would you go with?
   

1. ***
   given your time constraints and initial targets (mobile) your best bet is a CRUD-based approach (not SOAP, not Hypermedia). there are lots of tools already available and most mobile devs understand that approach w/o much prompting. this _will_ make it likely you will have API drift and experience versioning problems over time, but that is something you can survive this initial round w/o too much hassle, i suspect.
   ***

1. Is it realistic to be building the client in parallel to the API to support it? I'm hoping so as I'm assuming the actual app will be the use-case/proving ground for the API on which it relies.
   

1. ***
   if you/your team are building both the initial client and the API, this is a great rapid approach for the first cut API; esp. if you are using the use-case approach. client devs will tell you what they need, API team can craft the URI and corresponding bodies. while this does mean you'll have more API churn early, it should be worth it. 
   ***

1. Is it typical that the same team of people who build the API be responsible for the docs, or should I consider contracting a tech writer for this? We don't plan to have a public API till later so I'm hoping we can get by on our home-grown docs since our own teams will be the ones consuming them for the short to mid-term.
   

1. ***
   my advice is to keep the docs lean and compartmentalized. allow dev team to write the docs via inline code tooling or supply them w/ a simple template. make it as easy as possible for them. later, when you release a public API, you can judge if you want to bring in a professional writer to spruce up your dev-created content.
   ***

1. In general, any advice or thoughts on getting started? 
   

1. ***
   count on lots of tiny steps and many iterations on the API; the same as you do in any UX work. keep the steps small and you can likely maintain a good speed and get out a solid API ready for mobile users to quickly build you some cool apps.
   ***
   

Looking forward to seeing the results. looks like you have a great idea here.

Cheers.

mca

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

--
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+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

[Chad Alderson]

Wow - this is great Mike. Really appreciate all the insights here. Thanks for taking time out to help me out! What a great group.

[Samba NDIAYE]

Hello,

I could possibly help if you are looking fo a PaaS offering to run your API. In fact, I have been studying/experimenting with the APIGEE Platform and other services and it will be a nice fit for your project. You will get backend integration, analytics and moreover, develoers services.

feel free to contact me.

P.S: I could also build some tutorials, training and User and Administration guides in English & French

[kishorekumar]

Dear Chad,

From our experience in building Cloud Server(API) which interfaces to a Web App UX (Rails), CLI(Command line), Mob via JSON

Q1 Yes. But we did it midway as our Admin UX requirements weren't clear. Hence we did iteratively.
You can see our initial seed requirement.
We started with the Web App UX - (User/Admin skeleton) as seen in the above link. Then used themes to change them to this => landing_page, admin and parked our work.  Nothing was wired in detail, nor were the data model fully available.

Q2 RESTful - JSON works for us using HMAC (currently accessed via CLI, Rails). Our plans are to make it much robust using X509 in the next cut.

Q3 We worked on the client, once we had the cloud server(API) decently providing us the correct JSON (Success/Failure) for GET/POST.

Q4 In our case the team who built the API provided the structure for the doc (left links from this pic http://blog.megam.co/?attachment_id=954, and one API(Auth doc created) http://blog.megam.co/?attachment_id=957, whereas Account/others are sort of blank). Our plan is to get help from newbies/interns who can test the API server, and update the doc with the URL, Header, Body, JSON response. The dev team verifies and provides any input as needed and merges the pull request(commits to Github).

Q5 Our way through was -> 1. Client UX build it to a certain level, 2.Build working API server (core REST resources working), come back and nail the client UX, CLI. We access our Cloud API Server using an intermediary native wrapper (eg for Ruby: , Scala )

In the next couple of weeks the plan is to start Mob (based on Sencha)

(PS: We are just a bootstrapped start-up - team of 3)

With Warm Regards,
Kishorekumar Neelamegam,
Founder, www.megam.co ; Megam Systems;
email: nkis...@megam.co.in; twitter: @indykish; cell: +91 98405 59300 
blog: blog.megam.co |code: github.com/indykish

[erewhon]

I read Mike's excellent response and wanted to comment on the following:

My advice is to commit to use-case approach and stick to it.

Wouldn't it be true that the use cases (and their representations) change more frequently than an object-driven scheme?  Would choosing to build a use case oriented URI resourcing scheme cause more contract and development churn than its counterpart?  Perhaps an object-oriented scheme is more difficult up front, but with improved composability it might be more beneficial this early in the project.

[Jørn Wildt]

> Would choosing to build a use case oriented URI resourcing scheme cause more contract and development churn than its counterpart?

Well, as long as you only add new resources (and fields) to your web API, as opposed to changing your resources all the time, then it shouldn't be a problem.

See for instance Mark Nottingham's excellent article "Web API Versioning Smackdown" here http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

/Jørn

[erewhon]

Yup, familiar with that article ... I guess what I'm wondering is whether or not use case orientation will promote more churn on representations (e.g. "our client's admin dashboard is now three different task-based screens that we want to expose over the API as use cases ... API team please build that for us" vs "hey we can just recompose the API's object-oriented resources to produce the new flows ... API team please do nothing :P").

[Jørn Wildt]

> I guess what I'm wondering is whether or not use case orientation will promote more churn on representations

It sure will. You have two choices:

1) You choose resource representations, fix them and force clients to use them. This will force the client devs to use sub-optimal resources for their use cases. Your team saves work resources spent on developing. The client devs pays for it and the end user performance will be sub-optimal.

2) You listen to your client devs and evolve your API resources according to their needs. The client devs save work resources and the end user performance will be better. Your team pays for it.

Take a holistic look at it and choose what you want to optimize for: end user experience or resources spent in your department?

I would suggesting looking at your own team as a service provider for the client devs - and then provide good quality service by listening to their needs and evolve API resources accordingly. The client product will improve from it. Your team will initially pay for it - but if your team and the client team work in the same company then it shouldn't matter ... given that your management can take a holistic view on it and consider the total cost and end result.

/Jørn

[erewhon]

Yes, this makes perfect sense.  I think my above comments were musings on the implications of the 2 approaches to URI/resource design and seemed worthwhile raising in this thread.  I think you've summed up the concerns pretty well.

[Jack Repenning]

On Sep 10, 2013, at 8:28 PM, erewhon <keith....@gmail.com> wrote:

Wouldn't it be true that the use cases (and their representations) change more frequently than an object-driven scheme?  Would choosing to build a use case oriented URI resourcing scheme cause more contract and development churn than its counterpart?  Perhaps an object-oriented scheme is more difficult up front, but with improved composability it might be more beneficial this early in the project.

A "Use-case approach" should not be taken to mean "any random whim from the users is accepted without thought"! Customer emotions rarely make practical implementation specifications. As someone once told me, "The customer is always right, but the customer is always wrong."

A use case begins as a way to capture user input, but its next role is far more important: defining a language and understanding that allows you to discuss these requirements and trade-offs effectively.

[erewhon]

Of course, but use case oriented resources strike me as less reusable and more likely to change than the object oriented alternative.

[Jørn Wildt]

My guess is that most of the use case driven changes will be on the "read" side of the API with different representations/resources for different views and queries. The "write" side would probably be more static and more controlled by the API developers.

But, I am just guessing, it does after all depend a lot on the actual application domain.

/Jørn

[Jack Repenning]

On Sep 12, 2013, at 6:30 AM, erewhon <keith....@gmail.com> wrote:

Of course, but use case oriented resources strike me as less reusable and more likely to change than the object oriented alternative.

The "Use Case" community notion is that you use Use Cases to decide what needs doing. When that changes, you want to know. Nothing about a Use Case, even if accepted unaltered, particularly dictates whether the Use Case is satisfied by a change in t he resource, a change in the back end, a change in the human procedures around the API, or heck "wishful thinking." The REST API response to this is to keep the resources coherent and patterned, so programmers and both sides of the API can respond to changing Use Cases quickly and successfully.

The "Agile" community notion is that user demands can and do change, constantly. They tend to  use "User Stories" rather than "Use Cases"; roughly the difference being that Stories are simpler, easier to create, so you're less invested in them and can change them more readily. The REST API contribution to this is, once again, coherent, patterned resources to free everyone to do what needs doing.

It's likely true that user demands (whether expressed as Use Cases, User Stories,  or Random Whims Over Beer) change more often than actual implementations. It's almost axiomatic, in fact, since some user inputs get rejected, and some can be accommodated without a resource change, leaving fewer resource changes that user inputs. But "user-centered design" (to give a name to All Those Things Starting With A 'U'") is not a trade-off for "resource design." The U stuff is about "what needs doing"; the "r" stuff is about "how we get it done."