title: RESTful API and Foreign key handling for POSTs and PUTs
body: <p>I'm helping develop a new API for an <em>existing</em> database.  </p>
  
  <p>I'm using Python 2.7.3, Django 1.5 and the django-rest-framework 2.2.4 with PostgreSQL 9.1</p>
  
  <p>I need/want good documentation for the API, but I'm shorthanded and I hate writing/maintaining documentation (one of my many flaws).  </p>
  
  <p>I need to allow consumers of the API to add new "POS" (points of sale) locations.  In the Postgres database, there is a foreign key from pos to pos_location_type.  So, here is a simplified table structure.</p>
  
  <pre><code>pos_location_type(
    id serial,
    description text not null
  );
  
  pos(
     id serial,
     pos_name text not null,
     pos_location_type_id int not null references pos_location_type(id)
  );
  </code></pre>
  
  <p>So, to allow them to POST a new pos, they will need to give me a "pos_name" an a valid pos_location_type.  So, I've been reading about this stuff all weekend.  Lots of debates out there.</p>
  
  <p>How is my API consumers going to know what a pos_location_type is?  Or what value to pass here?  </p>
  
  <p>It seems like I need to tell them where to get a valid list of pos_locations.  Something like:</p>
  
  <pre><code>GET /pos_location/
  </code></pre>
  
  <p>As a quick note, examples of pos_location_type descriptions might be: ('school', 'park', 'office').</p>
  
  <p>I really like the "Browseability" of of the Django REST Framework, but, it doesn't seem to address this type of thing, and I actually had a very nice chat on IRC with Tom Christie earlier today, and he didn't really have an answer on what to do here (or maybe I never made my question clear).</p>
  
  <p>I've looked at Swagger, and that's a very cool/interesting project, but take a look at their "pet" resource on their <a href="http://petstore.swagger.wordnik.com/#!/pet" rel="nofollow">demo here</a>.  Notice it is pretty similar to what I need to do.  To add a new pet, you need to pass a category, which they define as class Category(id: long, name: string).  How is the consumer suppose to know what to pass here?  What's a valid id?  or name?</p>
  
  <p>In Django rest framework, I can define/override what is returned in the OPTION call.  I guess I could come up with my own little "system" here and return some information like:</p>
  
  <pre><code> pos-location-url: '/pos_location/'
  </code></pre>
  
  <p>in the generic form, it would be: {resource}-url: '/path/to/resource_list'</p>
  
  <p>and that would sort of work for the documentation side, but I'm not sure if that's really a nice solution programmatically.  What if I change the resources location. That would mean that my consumers would need to programmatically make and OPTIONS call for the resource to figure out all of the relations.  Maybe not a bad thing, but feels like a little weird.</p>
  
  <p>So, how do people handle this kind of thing?  </p>
  
  <p>Final notes: I get the fact that I don't really want a "leaking" abstaction here and have my database peaking thru the API layer, but the fact remains that there is a foreign_key constraint on this <em>existing</em> database and any insert that doesn't have a valid pos_location_type_id is raising an error.</p>
  
  <p>Also, I'm not trying to open up the URI vs. ID debate.  Whether the user has to use the pos_location_type_id int value or a URI doesn't matter for <em>this</em> discussion.  In either case, they have no idea what to send me.</p>