Don’t Make Me Think, When I Consume Your API

I recently worked on the voucher badge feature.  I needed to create an api endpoint to consume the voucher count, because we use services.

Unused Voucher Badge
The first iteration, the api passed voucher objects. However, I decided to refactor and pass the voucher count and less data between services, in hopes to shave couple milliseconds off load time. My first refactor looked like the following. Looking at the code, I know exactly what is happening and what data is being passed. It’s simple. 
unused voucher count as integer
Now imagine you’re consuming this new endpoint for the first time, with no knowledge of the implementation. You receive the following json object.  You might think, “Seven? what the hell does seven mean?” Then you’ll inevitably follow the source to VoucherController in order to understand.   

Instead, why not be explicit? Make it clear to everyone who consumes your lovely api what their getting back.

unused voucher count as a hash

That is so much better! Now I don’t have to visit the Api and look at the source code in order to understand what the object is.

So why not make others happy by telling them what their consuming, instead of making them think. Make your api intention explicit!
[EDIT]

Lets take this one step further and change our controller name as well. To be clear the vouchers controller only had one job of grabbing all unused voucher and returning the count. If it was part of a larger vouchers controller, I would have refactor it out instead .


Not only are we explicit with the object that is being returned, but the API name. I think this gives a better explanation of the api.

This post was based on a lightning talk I planned on giving at RubyConf 2014. However, the talks were cut short so I decided to make a blog post about it instead.

Standard

Learning How Startups Leverage Technology (DC Tech Meetup #30)

I attended the DC Tech Meetup #30 where I got the opportunity to listen and watch many different startups pitch and demos. The coolest thing for me was to see how these startups were leveraging technology to bring value to this world. I’ll go through each startup and explain what they do and share my thoughts about them.

Demo 1: Aspire (Neil Shah & William Huster)  – I missed this presentation

Demo 2: ID.me New Product Launch! (Blake Hall)

Idea – Verify people’s identity (teacher, military, student, etc) virtually.
Tech – Seems like a difficult problem to solve. Need multiple layers of clearance from the companies side and other agencies. Depending who is requesting information about the individual, they unlock multi-layer security. If it’s a higher security, then the software needs to receive a higher clearance more data to verify the user.

Overall(1-5): This idea is a note worthy 5. The team has proven that a pain point exist by reaching out to *retailers and other agencies that require identification clearance. They have built relationships with multiple different industry to leverage their technology.

*Retailers currently don’t give out discounts online, due to higher fraudulent claims. This is solved by Id.Me

Demo 4: Framebridge (Julia Lovett – julia@framebridge.com) 

Idea – Create custom frames that you’ll love

Tech – Mobile App that allows users to pick out a custom picture frame (with various sizes, colors, and patterns) with a feature to test out how it would look on your wall. Not complicated program. Straight forward main platform an section to choose in-stock frames.

Overall(1-5): Not the next million dollar idea, but definitely have potential. It’s a solid 2. It’s working in a highly niche market so it’s easier to target, but I don’t see how they can grow beyond the niche market. 

Demo 5: Vouched (Keith Cooperman)

Idea – LinkedIn like feature where users rate each other’s characteristics to see if they would be a good fit for a company.
Tech – A connection to users linkedIn profile, then leverage their contacts to rate others character traits. Manage multiple database table to store each users ratings, their average, and their contacts. Lot of different database involved to organize users feeds, ratings and information employees finds useful.

Overall(1-5): I’m personally very skeptical about this idea, because I don’t see any added value. It’s going to be hard to convince people that they need to rate their “friends” or “sort of friends” personality. First off why would I waste my time doing this (when I don’t even recommend skills sets of others). Second what is the different between endorsement in LinkedIn and this product?

Demo 6: Openreporter (Misha Vinokur – misha@openreporter.org)

Idea – Allow regular joe’s to report any noteworthy news to certified reporters.
Tech – Two different home page for regular joe’s and reporters. Regular joe’s needs to be able to post the situation. Both users need to communicate via comments on reports the regular joe’s make. Each report is pinned on a google map.

Overall(1-5): Overall it’s a solid 2. It’s an interesting idea, and innovative. However, I’m not sure how many reporters would want to quote a random guy who claiming “Dude I just saw t-rex riding on a elephant with a cow boy hat. It was awesome!” It’ll be bad journalism if they simply believed what people are saying. I want (video) proof. Second I guess they’ll charge reporters for this service or ads? Don’t see reporters actually paying initially (chicken and egg problem).   

Demo 7: AgSquared (Jeff Gordon)

Idea – Organize data about individual farmers crop type, yield, harvest, etc to analyze farmers data over the years to help them make informed decisions in future harvest/investments. There are sensors in place within the farm that collects data as well.
Tech – Probably the second hardest to implement after Id.Me. They use tracking within the farm and display the data through a graph on the farmers dashboard. The software analyzes the data (in ways the founder didn’t go into) for farmers to use.

Overall(1-5): I give them a 3 for two main reasons. The idea is relatively innovative and very useful for farmers in the long run. The negative is it’s very time consuming for farmers to actually input all the necessary data to make this useful. This takes time to learn to use the technology and take time out of actually labor.

Standard