title: Should I include URLs or Ids of resources in REST API response?
body: <p>I am designing a REST API. There's an entity <strong>Organization</strong> which may have a parent organization and multiple child organizations.</p>
  
  <p>Let's say a user does request <code>GET /organizations/1234</code>.
  What should I respond with?</p>
  
  <p>I can use URLs to these other organizations.</p>
  
  <pre><code>{
    "data": {
      "name": "Microsoft",
      "parent_organization": "http://api.myapi.asdfghj/organizations/1220",
      "child_organizations": [
        "http://api.myapi.asdfghj/organizations/1236",
        "http://api.myapi.asdfghj/organizations/1214"
      ]
    }
  }
  </code></pre>
  
  <p>or I can use their ids</p>
  
  <pre><code>{
    "data": {
      "name": "Microsoft",
      "parent_organization": 1220,
      "child_organizations": [
        1236,
        1214
      ]
    }
  }
  </code></pre>
  
  <p>Which one is better?</p>
  
  <p>If it's the one with full URLs, how do I do document that in swagger? Do I just set that as a string, something like the following?</p>
  
  <pre><code>definitions:
    Organization:
      type: object
      properties:
        data:
          type: object
          properties:
            name:
              type: string
            parent_organization:
              type: string
              format: url
            child_organizations:
              type: array
              items:
                type: string
                format: url 
  </code></pre>
  
  <p>What about <code>POST /organizations</code> for creating a new user? Should the user specify parent and children as urls too? </p>