Class Hoodoo::Services::Service < Object

Hoodoo::Services::Service is subclassed by people writing service implementations; the subclasses are the entrypoint for platform services.

It's really just a container of one or more interface classes, which are all Hoodoo::Services::Interface subclasses. The Rack middleware in Hoodoo::Services::Middleware uses the Hoodoo::Services::Service to find out what interfaces it implements. Those interface classes nominate a Ruby class of the author's choice in which they've written the implementation for that interface. Interfaces also declare themselves to be available at a particular URL endpoint (as a path fragment); this is used by the middleware to route inbound requests to the correct implementation class.

Suppose we defined a PurchaseInterface and RefundInterface which we wanted both to be available as a Shopping Service:

class PurchaseImplementation < Hoodoo::Services::Implementation
  # ...
end

class PurchaseInterface < Hoodoo::Services::Interface
  interface :Purchase do
    endpoint :purchases, PurchaseImplementation
    # ...
  end
end

class RefundImplementation < Hoodoo::Services::Implementation
  # ...
end

class RefundInterface < Hoodoo::Services::Interface
  interface :Refund do
    endpoint :refunds, RefundImplementation
    # ...
  end
end

…then the entire Service subclass for the Shopping Service could be as small as this:

class ShoppingService < Hoodoo::Services::Service
  comprised_of PurchaseInterface,
               RefundInterface
end

Names of subclasses in the above examples are chosen for clarity and the naming approach indicated is recommended, but it's not mandatory. Choose choose whatever you feel best fits your code and style.

Conceptually, one might just have a single interface per application for very small services, but you may want to logically group more interfaces in one service for code clarity/locality. More realistically, efficiency may dictate that certain interfaces have such heavy reliance and relationships between database contents that sharing the data models between those interface classes makes sense; you would group them under the same service application, sacrificing full decoupling. As a service author, the choice is yours.