search

xogeny / hyprofile

A Hypermedia API Profile Format
2 stars 0 forks source link

Composability #2

Open xogeny opened 6 years ago

xogeny commented 6 years ago

As mentioned in #1, a specification might potentially be a sub-specification of one section of the API or of some isolated and reusable set of functionality. In order to promote reuse of such sub-specifications, I need to think about how one might import such sub-specifications.

xogeny commented 6 years ago

Once approach could be to import external specifications with some defined scoping, e.g.,

{
  // Normal specification
  "import": {
    "sub1": "http://host/where/sub/spec/can/be/found.json"
  }
}

...and then import all the entities from that profile with the sub1 prefix to avoid namespace collisions. For example, a collection resource defined there would become sub1:collection.

While composability would be nice, I don't want this to turn into a case of the perfect being the enemy of the good enough. I primarily want to document and design an API, not design a whole framework for integrating APIs with namespaces, integration semantics, etc..