A JSON based Specification for API Discovery

api.json

{ "api": "Providers API",
  "description": "An api to access providers",
  "url": "https://api.itriagehealth.com/api/v1/providers",
  "resources": [
     "medical_facilities",
     "physicians"
  ]
}

spec.json

{ "resource": "Medical Facility",
  "description": "A medical facilities information and summary",
  "formats": ["json", "xml"],
  "authorization_type": "oauth",
  "authorization_types": ["oauth", "basic", "token"]
  "actions": {
    "index":  {
      "path":                   "/medical_facilities.:format",
      "method":                 "GET",
      "requires_authorization": false,
      "return_type":            "collection"
    },
    "search":  {
      "path":                   "/medical_facilities/search.:format",
      "method":                 "GET",
      "requires_authorization": false,
      "return_type":            "collection"
    },
    "create":  {
      "path":                   "/medical_facilities.:format",
      "method":                 "POST",
      "requires_authorization": false,
      "return_type":            "resource"
    },
    "read":  {
      "path":                   "/medical_facilities/:id.:format",
      "method":                 "GET",
      "requires_authorization": false,
      "return_type":            "resource"
    },
    "update":  {
      "path":                   "/medical_facilities/:id.:format",
      "method":                 "PUT",
      "requires_authorization": false,
      "return_type":            "resource"
    },
    "delete":  {
      "path":                   "/medical_facilities/:id.:format",
      "method":                 "DELETE",
      "requires_authorization": false,
      "return_type":            "success"
    }
  },
  "attributes": {
    "name": { "type": "string", "required": true, "readonly": "false", "actions": ["create", "index", "read", "update"] },
    "addresses": { "type": "array", "readonly": "false", "actions": ["index", "read"]  },
    "addresses_attributes": { "type": "array", "required": true, "readonly": "false", "actions": ["create", "update"]  }
  }
}

Search should have a :query var maybe?