Support/standardize semantic linking of input parameters with their output objects #728

Activity

1. KiaraGrouwstra commented on Jul 9, 2016

   

   KiaraGrouwstra

   on Jul 9, 2016

   Last edited by KiaraGrouwstra

   Author

   More actions

   edit: tl;dr I don't think we need spec changes, see my post below for a PoC.
2. MrTrick commented on Jul 10, 2016

   

   MrTrick

   on Jul 10, 2016

   More actions

   It's going to be difficult.

   1. The underlying json-schema concept for $ref does not restrict where it can point.
      (relative vs absolute vs external as a separate issue)
   2. There's no technical reason restricting where fields, parameters, responses, etc are defined. Convention dictates that shared response definitions are in the #/responses/ area, but one could just as easily (and a bit confusingly) define a response inline in one of the #/paths/... and $ref it from another path.
   3. The $ref address has no intrinsic meaning right now. I don't think tools do anything with it other than de-referencing, and maybe a little bit of validation to restrict where in the spec it may point.

   So, semantic linking is going to be an uphill battle!

   Also, convention is usually a better approach than restriction. Many many bug tickets and discussions start with "I have a reason to do this, but the spec won't let me!"

   One more issue with an implementation guessing how parameters link to response attributes, is the plenty of cases where it's not clear;

   • A parameter has to be a person id. Is it the primary key, the supervisor id, or the creating user's id?
   • A parameter has to be a date. Is it related to created/modified/etc, or something else entirely?
   • A parameter has to be a date. Is it an exact filter param, or a 'earlier than', or a 'later than' filter?
   • Cases where an input parameter relates to mulitple response attributes.
   • Cases where an input parameter relates to a different response attribute, depending.
   • More complex cases that any simple spec will be unable to capture.

   You'll need more than $ref. At the very least, response attrs will probably need to be linked somehow to filter parameters, not the other way round.
3. KiaraGrouwstra commented on Jul 10, 2016

   

   KiaraGrouwstra

   on Jul 10, 2016

   Last edited by KiaraGrouwstra

   Author

   More actions

   I'm cool with settling for convention where alternatives fail. In that event I guess OpenAPI could still add value there by encouraging good conventions.

   On ambiguities:

   A parameter has to be a person id. Is it the primary key, the supervisor id, or the creating user's id?

   • I suppose secondary keys in definitions could similarly be defined + semantically linked by a $ref (or whatever) to the original location/definition of the primary key. If we'd be able to link both this secondary key as well as the parameter back to the original primary key, I think that should give sufficient information to allow suggesting either id or supervisor_id fields of previously obtained User instances (including perhaps the creating User you mentioned) as potentially relevant inputs for this parameter. We can't read minds, but suggesting relevant options seems like a good start.

   A parameter has to be a date. Is it related to created/modified/etc, or something else entirely?

   • Use refs to whatever is appropriate -- the api spec writer has the freedom to distinguish such cases if needed.

   A parameter has to be a date. Is it an exact filter param, or a 'earlier than', or a 'later than' filter?

   • I'll concede additional info could well go lost as you're showing here. That said, I'd argue it's still better to be able to make whatever suggestions can be drawn from the info available.

   Cases where an input parameter relates to multiple response attributes.
   Cases where an input parameter relates to a different response attribute, depending.

   • Hm, maybe say anyOf with references...

   You'll need more than $ref. At the very least, response attrs will probably need to be linked somehow to filter parameters, not the other way round.

   • If I were writing an API description, it would seem easier if I could add an endpoint by being able to copy-paste parts from an existing one, rather than having to add to an array halfway across the document as well.
4. MrTrick commented on Jul 10, 2016

   

   MrTrick

   on Jul 10, 2016

   More actions

   You'll need more than $ref. At the very least, response attrs will probably need to be linked somehow to filter parameters, not the other way round.

   This differs from my conclusion, so might I ask you to elaborate on this further?

   • That $ref is an existing construct already used in all kinds of ways. Overloading and restricting it by way of adding semantic meaning is likely to make life harder for spec designers.
   • Abstracting for a moment the specific keyword used, there are two ways to have that link in the spec; "in param define effect on response" or "in response define how param affects it". I'll amend my previous comment, and say that either are doable.

   I do applaud your idea, but I'm not exactly sure whether you are trying to define a filtering spec, or define a mechanism by which a filtering spec may itself be defined?

   (If the former, then remember that the OpenAPI spec is meant to be API agnostic)
   (If the latter, then consider just how difficult it will be to support any API design!)
5. KiaraGrouwstra commented on Jul 10, 2016

   

   KiaraGrouwstra

   on Jul 10, 2016

   Last edited by KiaraGrouwstra

   Author

   More actions

   I'm thinking in terms of 'relevant suggestions' rather than 'filter'. This difference again sounds subtle, but the latter sounds like adding limitations, while I'd think of having better information as enabling rather than limiting.
6. KiaraGrouwstra commented on Jul 10, 2016

   

   KiaraGrouwstra

   on Jul 10, 2016

   Last edited by KiaraGrouwstra

   Author

   More actions

   On $ref vs. alternatives:

   • Does #/definitions/Person/properties/id contain sufficient info to infer (a) we're looking at a field of this model at #/definitions/Person, (b) that model is called Person, and (3) we're looking for its field at properties/id.
   • Yes, presuming (I) json-schema keywords like items, additionalItems, properties, patternProperties, additionalProperties, allOf, anyOf, oneOf and similar can be seen as indications that we've started navigating a model, and (II) we can just take the last path slice of the model (Person) as its name. If these assumptions appear to be somewhat sane/reasonable, then I think syntax would need to be no more complex than that of $ref.
   • alternatives: a new keyword e.g. links (array) or link (ref, optionally using anyOf).
7. MrTrick commented on Jul 10, 2016

   

   MrTrick

   on Jul 10, 2016

   More actions

   @tycho01 I think the more fundamental issue is deeper than any $ref or specific keywords.

   Consider the docs for the OpenAPI spec itself; "OpenAPI does not require you to rewrite your existing API. It does not require binding any software to a service--the service being described may not even be yours. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification."
   So let's take that as being "you should be able to implement a sensible API, (I know the docs go on to say it won't cover all APIs) and have the spec describe it".

   "Linking input parameters with their output objects" sounds to me like potentially a large flexible space. API A might use input parameters in a completely different manner to API B.
   Consider carefully what you'd like to achieve in an extension or enhancement here:

   • Option 1: Define a mechanism that improves the setup, code generation etc process for "API A"-like APIs. Hooray! - unless you have an API that's not "API A"-like.
   • Option 2: Define a mechanism that tries to improve the setup, code generation etc process for any kind of API - A, B, C... Much more difficult to do, and the creator of API D might still be unsatisfied with the options available within the spec.

   This sounds to me like a miniature version of what I've been cross with Swagger/OpenAPI about in the last few months;

   1. The "JSON-API" specification is one sensible way to design/implement an API.
   2. I've built a system that meets the spec, and I want to define a corresponding swagger spec, for documentation, etc.
   3. The Swagger/OpenAPI standard made it really difficult!
      • The existing json-schema describing JSON-API was considered invalid by strict swagger standards.
      • Many of the JSON-API standards weren't describable inside the swagger spec.
      • Much of parameters' semantic meaning (like `$ref:"#/definitions/person_id") was lost.
   4. So I'm stuck with keeping two spec documents;
      • one that's got all the features I want around validation, sanity etc. and
      • one that's dumbed down, but that conforms to the OpenAPI spec.

   Moral of the story? Don't go with Option 2 - that way lies disappointment confusion and anger. If not for the one defining that lovely mechanism, then for every author that comes around and is unable to use it to capture how their API works.
8. KiaraGrouwstra commented on Jul 10, 2016

   

   KiaraGrouwstra

   on Jul 10, 2016

   Last edited by KiaraGrouwstra

   Author

   More actions

   Thanks, that's a fair point. I'm definitely okay with not covering every single edge case.
   And perhaps by taking a few assumptions (notably (I), also (II)) I'm already trying to compromise a few edge cases for the sake of more common cases (tooling/description users who don't care and would rather have backward compatibility).
9. KiaraGrouwstra commented on Jul 19, 2016

   

   KiaraGrouwstra

   on Jul 19, 2016

   Author

   More actions

   I tried a quick PoC (i.e. I glossed over the complexity of JSON reference/pointer e.g. external/remote files) to demonstrate it's possible to gather the info with just $ref, so no changes to the OpenAPI spec, though @MrTrick's scenario ends up a bit different.
   As stated above, one can't just run the existing de$referencer in your language over an api spec and expect that to get you this info, but I'm happy this seems viable without changes.
10. KiaraGrouwstra

    closed this as completedon Jul 19, 2016