A Simple API Request/Response Decision Tree

I threw this together for work. I think it’s easy to get lost when designing APIs, web/software/whatever, but keeping this in mind can help you stay focused.

http://i.imgur.com/hdqMaxa.jpg

A Java Crash Course for Ruby Developers, Part 1

(Part 1 of a multi-part series. Introduction.)

Welcome! Let's get right to it. This is going to be largely unstructured and reflects the current state of my Java experience, which is very little. It will hopefully help other devs who are getting started. I expect that:

  • You know some basics about Java
  • You know Ruby basics

I'm not going to mention many things that should be obvious, like... lines are terminated with semi-colons, Java is not sensitive to whitespace, etc,...

Let's do this.

#### Use an IDE for Development.

While you can use a text editor to write Java, every resource I encountered referenced some IDE or another. The two big ones seem to be Eclipse and NetBeans. I ended up with NetBeans, though I honestly can't remember why. Having just switched from SublimeText to RubyMine, this was a pretty easy transition for me, as NetBeans feels a hell of a lot like RM, but it might take some getting used to for you. (Incidentally, JetBrains are the developers of IntelliJ, a Java IDE that I imagine is pretty amazing. It's also not free, so...)

If this is your first time using an IDE, the key features that I can no longer live without are:

  • Command + Click on a method to find its definition.
  • Right-click a method and click "Find Usages" to find everywhere that it's used
  • Highlight, right-click, "Refactor" menu to easily move pieces of code into methods, new classes, sub/parent classes, etc,...
  • Built in test integration and compilation
  • Easy dependency management
  • Flagging unused variables and dependencies
  • Hints RE: object types required during method calls or class initialization

Focus on that and you'll adjust in no time.

Don't start from nothing. Find an open source project to modify.

Starting a new language can be daunting, especially something like Java that introduces some concepts that are very different from Ruby. I set my sights on GraphAware's TimeTree plugin for Neo4j, found where the public API endpoints were exposed, copied the methods, and started modifying from there. Anyone who learned HTML in the days before CodeAcademy and sites like it will probably have done this at some point.

Plan on writing tests.

Because Java is compiled, it's very annoying to test your code by poking at it in your app. Write small methods, test carefully, and you'll save yourself a lot of time. There's JUnit, which uses methods and simple assert methods to test behavior (sound familiar?) and there's also Cucumber-JVM, if you're more comfortable there.

Class Definitions

One of the hardest parts of figuring out Java for me was just reading the damn code. You should already know that Java is strongly typed, but... final? Static? Void? WTF? This ends up being very easy.

Basic class Signature Examples

The typical Java class signature looks like this:

public class MyClass {}

That makes sense, right? public, protected, or private define visibility, just like Ruby. The rest is self-explanatory. Java has single inheritance and uses extends, so:

public class MyClass extends AnotherClass {}

Interfaces

Instead of modules, Java has interfaces. An interface lists methods that must be implemented in the class. It deals with what is there but not how they will behave. (NOTE: In Java 8, you can define default behavior for interface methods. This helps you out in the event you want to add a method to an interface that is widely implemented.) A class that includes an interface looks like this:

public class MyClass implements MyInterface {}

At that point, any methods defined in MyInterface are expected to also be defined in MyClass. If they aren't and default behavior isn't provided in the interface, your code will not compile.

Interfaces are extremely helpful because when it comes to method signatures, you can say that a method expects or returns a MyInterface instead of MyClass. It would be like doing this in Ruby:

module MyModule; end
class MyClass
  extend MyModule
end

# Will return true
MyClass.new.is_a?(MyModule)

Ruby doesn't work that way; instead, we'd use respond_to?, but Java's way gets us to the same place by a different route: we are checking that a given object has specific behavior implemented. We care less about the object and more about what it can or cannot do.

There's a lot more to interfaces than I'm going to get into now, but this is a good start.

There is no initialize method, but...

Instead of initialize, you define a method of the same name as the class and do not include a return value.

public class MyClass {
  public AnotherClass myVar;

  public MyClass(AnotherClass myVar) {
    this.myVar = myVar;
  }
}

That means that MyClass is initialized with one argument, an object of type AnotherClass, that will be referred to within its init method as myVar. Once instantiated, myObj.myVar will be set to this argument. For example:

# Define the variable
MyClass myObj;
# Instantiate the object
myObj = new MyClass(myOtherObj);
# call `myVar`, will return `myOtherObj`
return myObj.myVar;

There can be multiple constructors for a class

Java makes it possible to instantiate a new object using many different arguments, just define multiple constructor methods.

public class MyClass {
  public MyClass(AnotherClass myVar) {
    # do something
  }

  public MyClass(DifferentClass myMar, AnotherClass myOtherVar) {
    # do something
  }
}

Of course, the constructor methods would do something with those vars. Point is, you have flexibility in how you instantiate objects. This same rule holds true for methods.

Method definitions

Basic Method Signature Examples

Method signatures can omit visibility and will default to public but the best practice seems to always include it. They look like this:

public ReturnType methodName(FirstArgClass firstVar, SecondArgClass secondVar) {
  # Some code
  return # something here
}

Note that every method identifies not only what types of objects it expects but what it returns. To define a method that does not return anything, use the void keyword.

public void ReturnType methodName() {
  # do something but do not call `return`!
}

To define a class method, use the static keyword.

public static ReturnType methodName() { return null; }

Method arguments are typed

Method arguments follow the simple pattern of ObjectType variableName, separated by commas.

public String myMethod(String firstVar, int secondVar) {
  return firstVar;
}

There's not much more to it than that.

Variables

Variables are declared with types

This shouldn't have to be said at this point but:

String myVar;

That would allocate memory for a new String with name myVar.

Declarations can be assigned immediately... but this does not seem to be best practice

You can do this:

# assume `thisOtherMethod` returns something of type MyObj...
MyObj var1 = thisOtherMethod(anotherVar);

My IDE corrects me when I do this, though, so I get the sense that it's a best practice to declare first, then assign.

Instance variables

Define instance variables in the body of your class.

public class MyClass {
  public String myString;
  public List myList;
}

Those can now be assigned within methods. This is the equivalent of @var in Ruby.

Class variables

Define class variables using the static keyword in the body of the class.

public class MyClass {
  public static String myString;
}

Constants

Define constants using both static and final.

public class MyClass {
  private static final String myString = 'oh hai';
}

The final keyword indicates a value that cannot be changed.


That's it for now. Keep an eye out for part two. Hope this helps someone out.

A Java Crash Course for Ruby Developers, Part 0

I've been working with Neo4j for something like two years now. I started with Ruby and Neo4j.rb 2.3, which used JRuby 1.7.x with Neo4j Embedded 1.9, and learned Ruby, Neo4j, Rails, and the Neo4j.rb gem concurrently. Funny as it might be, I made it pretty far without ever writing much more than an extremely basic Cypher query for over a year. Phillymetal.com is built entirely on this stack but there's very little "graphy" stuff going on. Neo4j Embedded is so fast that working with the database has almost no overhead for simple find/return/traverse operations, so I was mostly exploiting the easy data modeling and schema-free goodness.

Things changed last year when I started contributing heavily to the Neo4j.rb gem, then got even more intense when I ramped up work on my own project. As performance became more of a concern, I started writing more Cypher to limit the number of queries in and out of the database. As it turns out, Ruby seems to be Neo4j.rb's biggest problem, but the fact is still that the REST API with Neo4j 2.1.7 is just not as performant as Java and Neo4j Embedded.

Enter unmanaged extensions and the Java API. Neo4j has a very cool feature: since it is open source and exposes a REST API, they provide an easy way to write your own plugins, "unmanaged extensions," that expose new REST endpoints. Once your data hits that endpoint, you can use the Java API to do all your work, then you return whatever you want back to your application. This gives you the best of both worlds: Cypher when you need it, Java API for the heavy lifting. Without exception, everyone I know who needs serious performance from Neo4j has told me that they fall back to this method.

At work, we're building an ambitious social media analytics platform that relies heavily on Neo4j. It's collecting a lot of data and revealing a lot of interesting connections. The front-end app is a client of the JSON API my team is building and the goal is for it to have the feel of a desktop app. This means it wants a ton of data very fast. Unfortunately, the combination of our query, the amount of data, the REST API, and Neo4j.rb just do not make for the performance we're looking for. Without getting into how much data we're returning, I can say that we've been seeing 1.5s responses when we really need something closer to 400ms.

I took some steps to improve performance but each time, I got smacked down. I patched Neo4j-core's Query class with an unwrapped method that returns simpler objects, I implemented the amazing GraphAware TimeTree plugin, I optimized the hell out of my query, but we were still having these issues; in fact, the 1.5s response mentioned above is AFTER these optimizations!

After hearing so much about the power of unmanaged extensions, I thought this might be a good opportunity to dive in. Problem was, I had never written a line of Java before. Hell, I had never successfully read a line of Java! Still, I knew what I wanted to do: take the complex Cypher query we're running, rewrite it in Java, return JSON that is usable in the app. To do this, I started looking for resources about Java that were aimed at Rubyists. I figured that with the popularity of both languages, there had to be something out there for Ruby devs looking to learn Java... right? Wrong. Everything I could find was about going from Java to Ruby. Coooool...

I figured I might as well dive into TimeTree to see if I could figure some of it out. I started with the API, since it was all I was really interacting with directly. https://github.com/graphaware/neo4j-timetree/blob/master/src/main/java/com/graphaware/module/timetree/api/TimeTreeApi.java has all the endpoints and figuring out what methods were being called was easy enough. It was also pretty trivial to expose a new endpoint, take a few params, and... make the whole thing crash. A lot.

A few searches and half a book on a plane ride later, I made it to a point that I was able to hack together my own unmanaged extension. In the span of seven days, I was able to write it, extract it from TimeTree, test it, and get it into staging. Our report now runs at around 400ms and I'm going to move more of our app's code into Java ASAP. Victory!

I'm writing this post and what I hope will be a few companion pieces for two reasons.

First, from a Neo4j dev's perspective, I want to illustrate the power of the Java API compared to Cypher. This is not a knock on Cypher in any way, because it is a fantastically expressive, readable, powerful language that I'm always happy to work with, but the superior control you have over your data within Java just can't be understated.

Second, separate from Java, I want to provide a resource for other people who may be in my shoes: Ruby devs who want or need to learn Java quickly but don't want to read through a book that spends a significant amount of time on familiar principles of OOP. As I work with Java, it's going to be harder to remember how I felt about it when I got started, so now is the time to do this.

I don't expect there to be more than one or two other posts about this and I doubt that either of them will be very heavy on Neo4j, if they're mentioned at all. Though I may mention it, it's really not much more than a reference for how I figured some things out. If you are an experienced Java developer, please don't blast me if/when I misstate details, since I'm still learning here.

I'm going to start working on the first piece of this immediately, so stay tuned!

2014: Best/Worst Year in Review

While this blog might not really show it, 2014 was one of the best and worst years of my life.

Professionally, it was a landmark year. In March, I left my job with Valiant Technology, the place that got me out of Philadelphia and into NYC. The end of my time with Valiant also marked the end of my time in that part of the IT industry after nearly 10 years. Goodbye, Hyper-V; hello, Heroku.The plan was to get a startup off the ground. It didn't exactly work out that way, but something even better happened: I realized how much I needed to grow by allowing Neo4j.rb to consume me.

Working with Neo4j and parent Neo Technology resulted in trips to Malmö, Sweden and San Francisco. It opened countless doors, helped me make lot of new friends, and helped me find a sense of both community and professional satisfaction that I've never really known. I wrote a lot of blog posts and made nearly 1500 commits on Github. Phillymetal.com relaunched, I participated in a whirlwind hackathon (that I'll link to when I move it to its new home), and just generally made a ton of stuff I'm extremely proud of. I put my ADHD hyper-focus to use and learned, learned, learned.

There was stress — a shitload of it. If not for the patience and support of my amazing girlfriend, who also left her job for the big ???? of freelance life only to end up in a fantastic new role of her own, I'd have been homeless or living on some generous person's couch sometime around September. I had some lucky breaks along the way (thank you, Utpal and Michael!) and just this morning, I accepted a full-time offer that came largely as a result of my obsessive open source work, dedication to not being shitty at things, and a whole lot of luck. This whole rags-to-something-better-than-rags story will make a better post sometime; for now, the point is that I feel as though it was all worth it because I no longer feel like I'm treading water in an industry that doesn't really have a future for me.

That was the good. It was a banner year, one I'll remember as a massive turning point thanks to the new opportunities and irons on the fire as we enter 2015. But if it was to sit on a scale, if I heaped in every single positive event, big and small, every tiny victory and massive conquest, and condensed it into something tangible, I don't think it could outweigh the single moment of devastation that occurred on January 29, 2014: my mom died of cancer. It crept up on us barely 8 months after it reappeared from 15 years of remission. Melanoma. She went into the hospital with stomach pain one night and was gone the next.

I haven't really written much about it and other than a post on Facebook and some time off of work and I don't think I've even typed it out in months. Seeing it on the screen still kind of feels like a shock. Things changed immediately after it happened: I couldn't handle life in the office, I couldn't deal with other people's schedules or attitudes — hell, I just couldn't deal with other people. A lot of my behavior since then — the decision to switch fields and work by myself from home, the unblinking focus on code, the freezing of every music project, silence on so many public tragedies that normally would have found me engaging in debate — I wonder how much of it was influenced by this. So much of this year was spent trying to process what happened. When the smoke cleared enough for me to see the other side, I think my priorities had changed. I found myself wanting to provide for my father, in whose household my mom was always CEO. I'm so much less interested in drama and dealing with personalities, which made me unwilling to pursue recording bands or playing shows or arguing politics or social issues. I'm filled with regret for things I never said or did. I like to think that I'm more careful with words, more deliberate with actions.

Even now, the world is darker, dirtier. It's as if everything is just slightly out of tune and I feel that dissonance all around me, subtle and unnerving; a constant, creeping vibration, profoundly wrong on a visceral level. For months, I kept waiting for my phone to ring and for someone to say, "Chris, we made a mistake! She's here, she's doing great!" Like a superhero who refuses to stay dead, cause nobody really stays dead, right?

No, the world doesn't work like that, and this is a part of life that every child eventually has to deal with. It's just frustrating that it should happen this year. I feel robbed of the opportunity to show her how things are working out, that her unflinching support and confidence for nearly 30 years wasn't misplaced. It's an incomprehensible feeling, to be so angry an existence itself but not really having anyone or anything specific to blame.

I try to reserve my blog for helpful things, how-tos and records of triumph, or at least cool things I come across as I go, but it didn't seem right to let this year close out without documenting 2014's twisting river of successful and failure. I don't mean to reduce the loss of my mother to some sort of apologue, but if I had to try and explain why I wanted to present this publicly, it would be to make a statement about the interconnectedness of all things. More than ever before, I am aware that we are all products of innumerable people's decisions and actions, nature's amorality, random coincidences, good and bad timing, and a whole lot of generous people. No matter how hard we work at things, we can take a step back and think about what led up to the opportunities, taken and missed, that shape our lives. Hard work is important, but so is awareness of the influence of everyone and everything around us; more importantly, we should take inventory of how cruelly fate could work out, how much worse things could always be.

I think of all the ways it could have been worse, of kids robbed of their parents as children, or kids who never know their parents, or kids who know their parents and hate them or are hated by them. My mom would tell me to think back on this year and be proud of my accomplishments, look after my father, love my friends and girlfriend, and do everything to the best of my abilities. She'd tell me to focus not on loss, but on success, the future, and the things I do have instead of the things I don't. It's a process, I guess, one I've never been very good at, but I'm doing my best, and I guess that's all anyone can really ask for.

Dynamically Adding Nested Resource Routes in Rails

I’m working what feels like a rather large project using the Neo4j.rb gem (which recently had its 3.0 release!). One feature of this project allows users to share different types of events with other users. Access to an endpoint in the API is based on whether a given user has a relationship to the target and, if so, some properties of that relationship. So, for instance, a User who has a direct relationship to an Event with the right score may see some restricted properties; a User who is related to an object that is related to that Event will see some limited properties; a User with no relationship whatsoever will not even be able to get to the page.

One of the nice things about the way this is setup is that all of the relationships share properties and some behavior, so it’s begging to be abstracted out into a module that I can test once and share with my resources. It also means that if I’m not careful, I’ll have to duplicate a lot of basic setup code: routes, controllers, etc,… I want to do this:

class Api::V1::EventsController & ApplicationController
  has_users_route

  # normal methods
end

…and have it automatically add a `:users` resource under `event`, so I can do `/api/v1/events/:event_id/users/:user_id` and it will route to the `UserSecurity` controller. This will prevent me from having to do this:

namespace :api do
  namespace :v1 do
    resources :events do
      resources :users, to: 'user_security'
    end
    resources :bands do
      resources :users, to: 'user_security'
    end
    # repeat about 15 times
  end
end

The question, then, is… how the hell do I do this? I did some research and found a lot of information on using Engines to add routes to apps, but this didn’t feel quite right. Someone on StackOverflow pointed me this. It was different from what I had in mind in that it was registering the new resources directly from `routes.rb`. At first, I didn’t think it was going to fit. I found a way to make it use a method in my controller, celebrated, began writing tests and this post… and realized that it was wiping out all the existing routes and just adding the new ones! Womp womp.

So I abandoned the idea of calling methods from controllers and I’m sticking it in `routes.rb`. This is smarter because (as we already covered) this really is a routing issue. By calling a method from the routes file, I can very easily manage which resources are taking advantage of this feature.

With all that said, my `UserAuthorization` module ended up looking like this:

module UserAuthorization
  extend ActiveSupport::Concern

  module ClassMethods
    def register_new_resource(controller_name)
      MyApp::Application.routes.draw do
        puts "Adding #{controller_name}"
        namespace :api do
          namespace :v1 do
            resources controller_name.to_sym do
              resources :users, controller: 'user_security', param: :given_id
            end
          end
        end
      end
    end
  end
end

`routes.rb` looks like this:

['events', 'bands', 'and so on'].each { |resource| ApplicationController.register_new_resource(resource) }

Calling `Rails.application.routes.named_routes.helpers` from the Rails console showed that my new resources were added. Victory! My request specs also suddenly changed and showed that my endpoints had come to life. There was a new problem, though, in the form of `params`.

It’s like this: since UserSecurityController is receiving data from any number of endpoints, I have a mystery resource and mystery param ID: `/api/v1/mystery_resource/:mystery_id/users/:id`. My controller actions need an easy way to get access to each of those and find the appropriate models the user is trying to load.

I started by trying to use the `param` option in the routes like this:

resources controller_name.to_sym, param: :target_id do
  resources :users, controller: 'user_security', param: :given_id
end

All that did was given me `param[:mystery_resource_target_id]` and `param[:given_id]`. The mystery resource — the target the user is trying to modify — was still unidentified, it just had `target_id` appended to it. Some more searches indicated that it might not be possible to change this, so I went in the other direction: If I can’t change the param’s key, I can figure out the path taken that ended up at the controller and set the param accordingly. While I was at it, I added a method to help me find the model that is responsible for the target so I can do things like `target_model.where(whatever)`.

Here’s the resultant class.

class Api::V1::UserSecurityController & ApplicationController
  before_action :authenticate_user!
  before_action :target_id

  private
  attr_reader :root_resource

  def target_id
    @target_id ||= get_target_id
  end

  def get_target_id
    @root_resource = request.fullpath.split('/')[3].singularize
    params["#{root_resource}_id".to_sym]
  end

  def target_model
    @target_model ||= root_resource.capitalize.constantize
  end

  def given_id
    params[:given_id]
  end
end

I don’t love how I had to do that but it gets the job done and I can and will always refactor. There’s still a lot to do but this is a start. Hope it gives you some ideas.

subscribe via RSS