title: Modeling API objects with respect to internal implementation
body: <p>If you create a REST service that serves <code>Banana</code> objects, there are likely two different conceptual models of those bananas.</p>
  
  <ol>
  <li>What is used on the REST API you serve to the public</li>
  <li>What is used internally to the application, with possible DB fields that aren't exposed externally</li>
  </ol>
  
  <p>One might reflect this reality in code by having two classes, with conversions between them:</p>
  
  <pre><code>class Banana {
    private String color;
  }
  
  class InternalBanana {
    private int id;
    private String color;
    private ZonedDateTime createdAt;
  
    public toBanana() {
      return new Banana(color);
    }
  }
  </code></pre>
  
  <p>Pros:</p>
  
  <ul>
  <li>Marshalling to Json via <code>jackson</code> is simple</li>
  <li><code>Banana</code> can be used while test-driving the API code</li>
  </ul>
  
  <p>Cons:</p>
  
  <ul>
  <li>Code duplication</li>
  <li>Converters of <em>internal</em> objects need to be updated any time the API is updated</li>
  </ul>
  
  <p>So what if we merge the two classes:</p>
  
  <pre><code>class Banana {
    private int id;
    private String color;
    private ZonedDateTime createdAt;
  
    public String toApiJson() { ... }
  }
  </code></pre>
  
  <p>Pros:</p>
  
  <ul>
  <li>No duplication</li>
  <li>Seems more robust to changes in the public API</li>
  </ul>
  
  <p>Cons:</p>
  
  <ul>
  <li>No model of REST API objects</li>
  <li>Marshaling to Json requires special code</li>
  <li>Internal fields will often be <code>null</code></li>
  </ul>
  
  <p>Which approach is likely to be the most efficient over the lifetime of a given service?</p>