Monthly Archives: July 2016

Reusable behavior in Ruby objects

Though my Forest project is still in its infancy (a mere 150 commits in), I have spent a great deal of my time wrestling with objects and the bridges between them. The hardest parts of the design are yet to come, like when animals begin interacting with (attacking? eating?) each other. But I’ve made a few major design choices so far.

Note: this article ends up kind of being a recapitulation of David Copeland’s very well-written and informative Re-use in OO, but I come to a different conclusion.

In particular, I’ve come to final (I think!) decision on how objects obtain shared behaviors.

Here’s the problem, in the most general sense: both Wolf and Rabbit should be able to change their location. They should be able to move. The code for movement should be shared.

Module mixins are not the way

My initial solution was to include a Movable module in both Wolf and Rabbit. This is the solution for which Copeland advocates. I walked pretty far down this path, and even found solutions to some of my problems, like that private methods defined in the included module are accessible to every other included module and the parent class. I wrote a blog post about my solution, but I mention at the bottom a remaining qualm: there’s nothing preventing a module from calling another module’s public method, as in this gist. They can do so easily and inexplicitly.

I envisioned a bleak future for my project, with included modules calling each other willy nilly, in all directions, forming intractable dependencies. This problem could be worked around by carefully maintaining unidirectional dependencies, but it would be ad-hoc and easy to break, unensured against by nature of the construct.

So I asked for help. My friends Devon and Forrest, fellow Dev Bootcamp grads (RACCOONS!), helped out. Forrest showed me the Copeland article, and Devon illustrated a technique of sharing behavior through composition.

A few acceptable solutions

Decorating objects to #move! through composition

What I’m going with is Devon’s suggestion. It has the benefit of ensuring that dependencies are explicit and travel in one direction. Additionally, instances only gain these abilities when you want them, rather than having always-on, and thus abusable, abilities.

This is an implementation of the decorator pattern, where Movable is the decorator. I was actually already using decorators in my code to create presenters (with view-specific logic), but I didn’t at first make the connection that it could be used to share behavior.

class Movable < SimpleDelegator
  def move!; ...; end
end

wolf = Wolf.new
movable_wolf = Movable.new(wolf)
movable_wolf.move!

Data, Context, Integration (DCI)

Jim Gay discusses DCI in-depth here, and I don’t understand it totally. Anyhow, it relies on modules extending objects as needed, rather than mixed into the class’s definition itself.

Note that usage is very similar to the previous solution.

module Movable
  def move!; ...; end
end

wolf = Wolf.new
wolf.extend(Movable)
wolf.move!

Duck typing your way to movement

Another composition / duck-typing solution is as follows, where the actual moving is delegated to another object or module. This is a partial solution.

I don’t like this path as much; I intuitively think that an object should be in charge of its own movement. I could envisage plenty of cases when it would be preferable, however, like if there was a Map object in charge of collision detection. You’d have to be vigilant in preventing the Map from becoming a God Object, though.

As stated, this is a partial solution. It doesn’t solve the problem of how to ensure a Wolf is a Movable in the first place. One could do that through extension or composition, as in the above two examples. It just changes where the #move! method lives, and implies that movement is the responsibility of a third object.

I like how “movable” makes semantic sense, though. And duck typing is just fun.

module Mover
  def self.move!(movable); ...; end
end

Mover.move!(a_movable_wolf)

Unsurprisingly

There’s more than one way to do it.

Module mixin on its own, my naive approach, seems totally untenable. It is multiple inheritance, as demonstrated by the fact that included modules are listed in a class’s .ancestors method. And inheritance can be a mess to begin with, without dependencies being able to go in all directions.

Please let me know if I you’ve got corrections or feedback! For example, I’d love to hear more examples of when the last code example is appropriate. I feel like it’s more useful than I am realizing.

Leave a comment

Filed under code, Uncategorized

Creating practically private methods in mixed-in Ruby modules

Module injection in Ruby is cool. It allows you to flexibly compose an object’s behavior (those it’s not composition; it’s multiple inheritance), while still leveraging the data/code coupling power of objects. However, it comes with its own set of complications.

A particular module might want to reduce its namespace footprint by exposing a small interface and hiding implementation functions. Take a look at the code in this gist. Both modules define an aptly-named private_method, but once they’re both included in the class, the second private method overwrites the first.

Ruby’s private keyword does not do what I want here, as methods defined within it share a namespace with all other included methods. You do not want a module’s private methods to have to compete for namespace, as no other parts of your code should even know they exist! This is a strong dependency.

There is an easy, common solution, but I have to admit that it feels hacky, and is certainly not semantic. By which I mean, this solution would never occur to me. But here: effectively private methods can be hidden within classes or modules defined within your original module, like in this gist. The idea is summarized as follows:

module MyFirstModule
  def first_public_method(my_string)
    return "#{my_string} #{PrivateMethods.private_method}"
  end

  module PrivateMethods
    def self.private_method
      1
    end
  end
end

This module can be included in your model classes, and Bob’s your uncle! The module exposes a public interface which makes use of private methods which truly do not effect anything else. It’s not too complicated, but don’t you agree that it’s a bit gross?

This doesn’t solve every problem of module injection, but it allows you to reduce surface area and make necessary dependencies more obvious. I’m currently trying to figure out how to prevent modules from being so easily able to call and depend on each other in inexplicit, unobvious ways. Like in this gist.

Leave a comment

Filed under Uncategorized

RESTful API design and implementation

Recently, while building the forest’s API and finding myself running into problems I’d never imagined would need to be solved, I realized that I know very little API design.

This implies I’ve learned some, and simply have a better view of the field than I did. This article (which concerns both design and implementation) discusses the things I have learned and contended with.

I’ve been reading https://geemus.gitbooks.io/http-api-design/content/en/, and studying a couple different APIs (e.g. GitHub, which is my favorite) to see how it’s done.

Anyways.

Versioning

APIs need to be versioned so that the developer can easily release new work. The two major schemes to expose different API versions: through request headers, and through the URI.

The header solution is the “most correct”, partially because it keeps URIs as an explicit and clean reference to a particular resource. Properly, the API version doesn’t have any bearing on the resource the client is trying to access, and thus doesn’t belong in the uniform resource identifier. That’s a sound argument.

However, several major players do use “api/v1/resource”, the improper and less technically RESTful method. And I’m doing it, too.

It’s easier for development. I don’t have to use curl or Postman to see what my responses look like. I can just visit localhost in browser. I also believe it’s a less opaque technique, and the only argument against it is an appeal to authority.

Here’s a good StackOverflow answer explaining why I’m wrong.

I agree that URIs should be permalinks, but a major API version change is likely going to introduce breaking changes. API consumers are going to have to change how they request the resource in any case. I’m much happier keeping the version totally in sight.

URIs dependent on params, not IDs

I want clear, beautiful URIs. Locations are best known by their Cartesian coordinates, not their IDs. Any Rails developer already knows that this is somewhat of a pain. Although custom routes are fairly trivial in Rails, these schemes can very quickly and easily get out of hand if not managed properly; such is Rails’ dependence on naming conventions.

I went through a couple thoughts on this, like for example /locations/x/1/y/2, but I eventually settled on a query string: locations?x=1&y=2

I found a couple of people discussing whether query strings are RESTful on StackOverflow. It would seem that there’s no reason for them not to be; REST merely asks that resources have unique endpoints.

Of course, dictating to Rails that I want every location’s URI to use the query string rather than an ID meant clobbering DMM’s opinions.

Here’s some of the weirder stuff I had to do to get this scheme to work:

JSON layouts

That bullshit concerning rails-api and JBuilder that I already wrote about.

It makes no sense that this isn’t built into rails-api. The main draw of Rails is that it’s opinionated, and thus does a bunch of heavy lifting for the developer at the cost of flexibility.

There’s a bunch of stupid rails-api stuff I’ve complained about on Twitter.

HATEOAS

This is a large topic that dictates much of the forest’s design. It’s taken a lot of work, and I barely have it in place. HATEOAS is an aspect of REST that most APIs do not bother with; developers (not unreasonably) expect consumers to rely on separate documentation to get around. GitHub is my model API because they actually do implement it, and they implement it well.

I would love some back-end framework that makes this easier, like Rails makes every other common task easier. That’s a niche I would have expected rails-api to fill. Yes I’m bitter.

HATEOAS breaks down into a few sub-issues.

  1. Return relative or absolute URIs?
  2. Where should actions be in the response? All at the top level in one list or object, or some actions per object?
  3. What do action routes look like?

So, 1), I’m going with relative, rather than absolute, URIs. A couple of the reasons for this are, unfortunately, because Rails makes it easier to use relative URIs. URL helpers like url_for and [resource]_url return relative URIs by default. Additionally, RSpec makes it hard to get(absolute_url), so I’d have to add a bunch more boilerplate to the tests.

Here is a good discussion on paths on StackOverflow.

Github uses absolute URIs for action routes. They say it’s so the client doesn’t have to construct the URI themselves. Fair enough; it does take a little work for the client to construct URIs with the scheme I’m using. However, they would probably only need to implement that solution once in that project. I don’t expect it to be too onerous.

2) Right now, actions in the API response are presented like this:

location: 
  actions: {...},
  objects: [{
    kind: wolf,
    actions: {...}
  }]

Actions are stored in location.actionsand in location.objects[i].actions. They are organized according to what the object the action is on, but as a result are scattered throughout the JSON.

I could also have a big ol’ hash or list at the top level simply labelled actions which would contain every action possible at that moment. It would be very easy to find, and namespacing actions within could help organize them.

My main concern here isn’t whether one thing is more correct that the other. I’m struggling with what solution would be easiest for the API consumer.

In terms of development from the API maintainer’s perspective, the current setup is easiest. So that’s that. If it turns out to be awful from the consumer perspective, I’ll look into changing it.

3) And what should actions look like? Specifically, let’s say hello to a wolf. Is that:

  • /wolves/1/action/say-hello
  • /wolves/1/say-hello
  • /wolves/1?action=say-hello

I’m pretty sure I’m gonna go with the second option, although if the forest ever has nested resources, it could get to be a problem. The solution is to say “no nested resources!”, but that seems pretty limiting. We’ll see!

Well

Designing and building this API has taught me so much that I didn’t know I didn’t know. It’s been so much fun! Because my collaborators (looks like Ryan‘s on board!) and I are basically the only people consuming the API, I have a pretty good idea of what the client’s needs are. Having to deeply consider both sides has given the process a lot of helpful direction.

Leave a comment

Filed under code, Uncategorized