Skip to content
Snippets Groups Projects

manager API: versioning

    • Closed Issue created by Vaclav Sraier @vsraier

    I think it's quite unlikely that manager's HTTP API will have flawless design from the start. At some point in the future, there might be a need to make a new backwards incompatible API. I think we should prepare for it now as it's still not too late and it's really easy to do so now.

    Ideas

    • version in URL path (/config/v2/...)
    • version in the configuration (that would allow us to change the schema, but not the API itself)
    • version in HTTP header (probably something like X-API-Version: latest or X-API-Version: 6.0.0)
    • ...
    Edited
    To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information

    Child items ...

    • Activity

    • Vaclav Sraier added manager label

      added manager label

    • Vaclav Sraier assigned to @vsraier

      assigned to @vsraier

      • Vaclav Sraier
        Vaclav Sraier @vsraier ·
        Author Maintainer

        I have two opposing takes on this:

        • The version information in the header allows the user to not care at all. However, when we upgrade, user's code will break until they fix their code with a header indicating older version.

        • The version information in the URL is forced to be there, nothing will work without it. Therefore, when we make a breaking change, the users won't need to update anything and everything will work.

        I somewhat like the header more. I think it's better when we let users know about changes in API sooner than later. However, I don't consider this a strong argument. Any opinions about this one?

        I also think, that it might be a good idea to version both the schema and the API. Not just one of them. Because HTTP headers are not stored in the config file... :smile:

      • Oto Šťáva
        Oto Šťáva @ostava ·
        Maintainer

        I personally like the URL variant more - seems cleaner to me in terms of HTTP and/or REST semantics. E.g. when deciding whether a resource exists on the server, it feels wrong to me to say that it does when using one header, and that it doesn't when using another (an exception to this logic being the Authorization header).

        As for letting users know about breaking changes, I'd opt for adding some kind of a human-readable deprecation field to the reply ahead of removing outdated APIs.

        About the schema versioning, I'm not sure about how that mechanism would work in practice. Would the manager be able/allowed to expose multiple configuration schema versions at the same time through the API? I would expect a schema version to be forced across the whole manager instance. Maybe, a header could be put in the request as a sanity check, returning a 400 on a mismatch... something like "hey, you seem to be expecting to work with schema v1, but this manager is using schema v2, you can't do that".

        Edited by Oto Šťáva
      • Vaclav Sraier
        Vaclav Sraier @vsraier ·
        Author Maintainer

        I agree with the API versioning...

        Would the manager be able/allowed to expose multiple configuration schema versions at the same time through the API?

        Actually, I think this is entirely possible. There is nothing preventing us from having multiple schemas of configuration functional at the same time. In the end, there is not that many options the manager is looking at. Most are just used to render a Jinja template and otherwise never touched. So as long as we can render the Lua config, the manager does not care how the schema looks.

        Even more so, I think we have to to support that. If we change the configuration schema, we have to be able to load the old config file. At least for a while during a transition period.

      • Please register or sign in to reply
    • Oto Šťáva
      Oto Šťáva @ostava ·
      Maintainer

      The X- prefix on non-standard HTTP headers is deprecated (RFC 6648). The current convention is to just name the header something that does not have a meaning in the current standards so that, if such a header becomes standardized in the future, one can avoid requiring migrations from X- headers to non-prefixed ones.

    • Vladimír Čunát
      Vladimír Čunát @vcunat ·
      Owner

      I can't say I'm knowledgeable about HTTP customs, but the URL way seems much better to me. And I think I have seen it in some larger API providers, e.g. https://docs.gitlab.com/ee/api/#how-to-use-the-api

    • Vaclav Sraier mentioned in commit 1d50a38b

      mentioned in commit 1d50a38b

    • Vaclav Sraier mentioned in commit fc757619

      mentioned in commit fc757619

    • Vaclav Sraier mentioned in commit 23174685

      mentioned in commit 23174685

    • Vaclav Sraier mentioned in commit 46cd4cd9

      mentioned in commit 46cd4cd9

    • Vaclav Sraier mentioned in commit 781ff86f

      mentioned in commit 781ff86f

    • Vaclav Sraier mentioned in commit 52dc483b

      mentioned in commit 52dc483b

    • Vaclav Sraier mentioned in commit 157d30fb

      mentioned in commit 157d30fb

    • Vaclav Sraier mentioned in commit 40a46e69

      mentioned in commit 40a46e69

    • Vaclav Sraier mentioned in commit d8e75690

      mentioned in commit d8e75690

    • Vaclav Sraier mentioned in commit 0ecbf6a7

      mentioned in commit 0ecbf6a7

    • Vaclav Sraier mentioned in commit 62647888

      mentioned in commit 62647888

    • Vaclav Sraier mentioned in commit bc0688b3

      mentioned in commit bc0688b3

    • Vaclav Sraier changed title from HTTP API: versioning to manager API: versioning

      changed title from HTTP API: versioning to manager API: versioning

    • Vaclav Sraier mentioned in commit 18d0d688

      mentioned in commit 18d0d688

    • Vaclav Sraier mentioned in merge request !1347 (merged)

      mentioned in merge request !1347 (merged)

    • Aleš Mrázek closed

      closed

    Please register or sign in to reply