New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JSON API spec is not versioned #46

Closed
b opened this Issue May 7, 2013 · 8 comments

Comments

Projects
None yet
3 participants
@b

b commented May 7, 2013

The JSON API spec itself needs version information. When one of those mythical changes for which the current spec needs "flexibility", the version would be changed.

@lukfugl

This comment has been minimized.

Show comment
Hide comment
@lukfugl

lukfugl commented May 7, 2013

👍

@steveklabnik

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik May 7, 2013

Contributor

Yes, when we have something that's reasonably "final" we can talk about this.

Contributor

steveklabnik commented May 7, 2013

Yes, when we have something that's reasonably "final" we can talk about this.

@b

This comment has been minimized.

Show comment
Hide comment
@b

b May 7, 2013

When the design is done the work to add any version information and behavior to the design will happen?

b commented May 7, 2013

When the design is done the work to add any version information and behavior to the design will happen?

@steveklabnik

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik May 7, 2013

Contributor

The version information is currently there:

This document is a work in progress and will likely change over the next month as implementation work progresses. Implementors should be aware that this specification is not stable.

I'm not comfortable with adding anything further than this at this time. This is a draft, a request for feedback. Things get official version numbers when they're actually final in some form.

Contributor

steveklabnik commented May 7, 2013

The version information is currently there:

This document is a work in progress and will likely change over the next month as implementation work progresses. Implementors should be aware that this specification is not stable.

I'm not comfortable with adding anything further than this at this time. This is a draft, a request for feedback. Things get official version numbers when they're actually final in some form.

@b

This comment has been minimized.

Show comment
Hide comment
@b

b May 7, 2013

Think you're misunderstanding. A JSON API speaker needs a way to signal which version of the protocol it supports, regardless of what the current version number on the spec is. The mechanism needs to be part of the spec, even if the current document doesn't have a version.

b commented May 7, 2013

Think you're misunderstanding. A JSON API speaker needs a way to signal which version of the protocol it supports, regardless of what the current version number on the spec is. The mechanism needs to be part of the spec, even if the current document doesn't have a version.

@steveklabnik

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik May 7, 2013

Contributor

Yes, I did misunderstand, thank you.

My inclination is that most media types do not present an internal version, because the commitment to backwards compatibility is so great. That said, no official decision has been made about this, so I'll re-open it until we discuss it formally.

Contributor

steveklabnik commented May 7, 2013

Yes, I did misunderstand, thank you.

My inclination is that most media types do not present an internal version, because the commitment to backwards compatibility is so great. That said, no official decision has been made about this, so I'll re-open it until we discuss it formally.

@steveklabnik steveklabnik reopened this May 7, 2013

@b

This comment has been minimized.

Show comment
Hide comment
@b

b May 7, 2013

Version information can be expressed and negotiated in numerous ways, media type being one. I'm not pushing a specific mechanism, only urging strongly that there be one, and soon. Versioning of APIs and versioning of resources are also missing or underspecified, but are being handled in other issues.

b commented May 7, 2013

Version information can be expressed and negotiated in numerous ways, media type being one. I'm not pushing a specific mechanism, only urging strongly that there be one, and soon. Versioning of APIs and versioning of resources are also missing or underspecified, but are being handled in other issues.

@steveklabnik

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik May 9, 2013

Contributor

After a discussion with @wycats, we plan on doing the usual media-type thing: never remove, only add. Therefore we don't need explicit versioning after we declare it stable, as it will always be backwards compatible.

I've updated #1 to add things around versioning your entire API.

Contributor

steveklabnik commented May 9, 2013

After a discussion with @wycats, we plan on doing the usual media-type thing: never remove, only add. Therefore we don't need explicit versioning after we declare it stable, as it will always be backwards compatible.

I've updated #1 to add things around versioning your entire API.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment