Joe Conley Tagged point.io

Building better APIs with Play!

Tue, 04 Mar 2014 00:00:00 +0000

This is the technical companion to my Point.io post, Building better APIs with Play!. Herein lies coding examples galore!

RESTful Architecture - Routing

The routes file of a Play app allows you to define the HTTP verb, the route path/pattern, and the corresponding method from the controller. In addition to denoting basic path variables, you can also use regular expressions to match on specific routes (i.e. xml or html formats for example). What’s great about this approach is this file is compiled along with the source code, so any mistakes like an incorrect controller method or invalid HTTP verb will be caught and thrown at compile time.

Action composition

We define two types of custom actions: atomic and composed. Atomic actions can be used stand-alone or as building blocks to be composed with other actions. We use the following pattern for building an atomic action.

The object allows us to use the action by itself, and the case class allows us to compose this action with other actions.

A composed action is strictly syntactic sugar, making it more convenient to combine behaviors and keeping the controller code more concise. We define composed actions using just an object.

Filters

Filters are handy for cross-cutting concerns. We’ve had one use case where it was necessary to modify every JSON response with links to metadata. We achieved this using a filter and the Play Enumeratee library

JSON - Global messaging

Building an effective API requires being responsive to users in a comprehensive manner. All concievable events should be handled appropriately, such as incorrect requests from the client or internal server errors. Creating a Global object allows you to generically craft responses to handle these situations. We define methods to handle events like internal errors, route not found, or a bad request.

Conclusion

Play is well-equipped to handle the nuances of API development and maintenance. We’re pleased with the stability and performance we’ve seen thus far and are looking forward to continuing down this path of reactive goodness.

(Triz)Swagging out at the Philly Codefest

Tue, 25 Feb 2014 00:00:00 +0000

This past weekend I teamed up with some buddies from Point.io (Angel, Jon, and Dylan) to participate in my first hackathon, Philly Codefest. We spent the weekend bringing Angel’s dream to life: a platform called TrizSwagger to analyze and track the use of “swag” (i.e. T-shirts, office supplies, and other marketing mathoms). We leveraged social media and geolocation to give companies real-time visibility to their marketing campaigns. Feel free to check out the app here.

Angel demoing Point.io's apiDoc service

Lessons Learned

Good programming is always concerned with simplicity and efficiency, whether it’s using efficient data structures and algorithms, conciseness in your codebase, or even naming variables properly. Building an app in 24 hours, however, throws the need for simplicity and efficiency into sharp relief. Here are a few takeways from my experience.

Coast-to-Coast JSON

I’ve always been a big fan of Domain-driven Design. Writing POJOs in Java and case classes in Scala can provide a clear crystallization of the main actors of your application. However, models may not always be necessary, especially if your app is backed by a service/database which gives you JSON (TrizSwagger is backed in MongoDB and served by Flask). The extra layer of complexity in marshalling/unmarshalling between JSON and your model can hinder performance and readability of your code, especially if you’re using heavy ORM frameworks like Hibernate. During a hackathon, if you’re rapidly making changes to the model you’ll surely get slowed down. For a more thorough treatment of JSON Coast-to-Coast, check out the Mandubian Blog

Knockout.js Mapping plugin

In order to implement coast-to-coast design effectively, it’s important to have a front-end framework that manages JSON well. One such framework I’m fond of is Knockout.js, more specifically their mapping plugin. This plugin automatically maps a JSON message into a Javascript observable object. You can then code the front-end directly against object properties without having to pre-define a viewmodel. You can also customize how objects are mapped by either modifying or enhancing the created object. This strategy proved quite helpful during the hackathon as any changes to our back-end API literally only had to be changed in one place (the front-end).

One caveat is the creation of a new object using this plugin. Since the plugin requires a JSON object to build out the observable, I wrote a basic method in Play to take an expected JSON object and “empty” it, setting default values that would be used in the new object form.

Understanding your tools

TrizSwagger integrates with both Twitter and Facebook. Understanding and setting up those integrations, however, occupied a lot of our time. We also ran into issues with a server on OpenShift, slowing us down further. Ultimately I think simpler is better, and every choice in technology needs to be well thought-out and well-suited to its use case.

Conclusion

Overall it was an awesome experience. Even though we didn’t win (or place, or show for that matter), we learned a lot and we still took the time to mentor other teams who were using the Point.io API. Great job Team TrizSwagger!

Jon, Dylan, and Joe doing some last-minute coding

Scala 101

Wed, 29 Jan 2014 00:00:00 +0000

I recently gave an introductory talk about Scala for my unintiated Point.io hackers. Here’s the slides for future reference. Enjoy!