1

I've been pinging get requests to the REST API on our instance. For some reason this seems to get set to v26 of the API.

I am assuming this version parameter is returned from a setting somewhere in my instance* and is not something defined by my request (do set me straight if that's incorrect).

So, what defines the API version, is it set at an Instance level or is it something set on a per-object basis?

I also understand that the versioning is progressive and appears to only add new methods and not deprecate old ones... if there is a switch somewhere I could throw to move my api request versions from v26 to v30+ what are the potential migration gotchas people have run into?

*Update - This assumption turned out to be incorrect, see below

Huw
  • 275
  • 4
  • 13
  • What do you mean by 'locked". Do you mean it hangs? Timeout? Is it all requests, or just certain ones? – pchittum May 13 '15 at 11:42
  • Sorry locked was not clear - I mean that's what is returned in the URL. My workflow is to use a ROR library - restforce to manage an Oauth login to salesforce, generating an authenticity token and then dispatching requests from there. All these requests are pointed at /services/data/v26.0 which I haven't explicitly set - so I'm assuming this is keyed off some aspect of my instance / object. – Huw May 13 '15 at 11:57
  • 1
    As it appears you have discovered, your integration library is defaulting to an older version. I've posted a comprehensive answer that may help you understand the underlying process of what is going on, and help you decide which version to use (typically the latest, which is currently v33.0). – pchittum May 13 '15 at 12:24

3 Answers3

4

API version is defined in different different ways depending on what you are doing with it.

  • SOAP API calls
  • REST API calls
  • Apex
  • Visualforce

All of these (and other features that use API) are fixed in the code you write against them, allowing you to upgrade/update when it fits your company/project lifecycle. Integration uses different end points. Apex and Visualforce use metadata to define the version.

Essentially there is only ever one version of Salesforce in production. Previous versions of the API are emulated for the purpose of integration and code resilience.

So when you write your REST request (as that's what you've been using), you will use a URL like this, for instance: 

HTTP:GET
/services/data/v26.0/sobjects/account/001B0000003nJhJIAU

The v26.0 segment of the URL path is what stipulates the version. You can substitute any other previous or later version up to the current version (v33.0 for Spring 15, the current release).

The thing is, there is no guarantee it will be supported. For instance if you were to make a GET request to this URL:

HTTP:GET
/services/data/v20.0/sobjects/FeedItem

It would fail stating that this "service does not exist". The FeedItem object didn't exist in that version. It's predecessor FeedPost was used for that at the time.

In some instances you will get a response, but a different result. For instance these two GET endpoints: 

/services/data/v26.0/sobjects/account/001B0000003nJhJIAU
/services/data/v33.0/sobjects/account/001B0000003nJhJIAU

The second returns a few extra fields that were added in the ensuing versions (I forget exactly which version...somewhere around 30, I think) for geolocation called longitude and latitude.

And another example: 

HTTP:POST
/services/data/v33.0/composite/batch

In this instance, it won't work, but that's because it will not be available until version 34 of the API. But if you get a pre-release org, you can do the same with the updated API version (although you need to post some JSON in your request body for it to work): 

HTTP:POST
/services/data/v34.0/composite/batch

As for considerations for when to upgrade...I wrote this answer about that. It pertains to Apex code, but the same principle applies: upgrading your integrations/code arbitrarily because Salesforce did a major release is just giving yourself extra work.

New releases bring new features. When your integration needs to make use of a new feature, that's the time to upgrade, and only the integrations that need the new feature.

Salesforce still has working integrations against every version of the API. If it is new build, always build against the newest version. If you have to write code against an existing integration, evaluate an upgrade at that time.

Finally, I don't know what tool you are using for your testing, but it sounds like it might be defaulting to a previous version of the API and maybe overriding your requests? If so, it is the tool. Salesforce always takes the requested API version and responds in kind. If you want to get to know the REST API, I'd suggest spending some time using the workbench.

The login page needs to be updated to use the latest version, but if you go to the REST Explorer, you can override the login version for request testing. In this screen shot, you can see I'm using v34.0 against a pre-release org. Production orgs will only work up to version 33!

enter image description here

Community
  • 1
pchittum
  • 19,701
  • 5
  • 54
  • 97
  • Excellent answer - many thanks. I suspect my confusion is due to me sending requests to any custom apex but rather methods like describe and describe_layouts, which I guess will always be geared to the latest api v. Your clarification is very helpful! – Huw May 13 '15 at 12:25
  • 1
    Take a look at the REST explorer in workbench. The describe and describe_layout resources are versioned (i.e. /services/data/v33.0/sobjects/Account/describe/layouts). They are abstracted by the restforce lib is all. – pchittum May 13 '15 at 12:32
  • been using that a lot it's a great resource for anyone who's a bit of a salesforce/api noob to get to know the API better. All issues stemmed from my request leaving me with /services/data/v26.0/... and thus none of the newer (cooler) methods. – Huw May 14 '15 at 11:52
  • Thanks! Do you know of a page on the Salesforce site that confirms your statement that they support "any other previous or later version up to the current version" ? I only found one statement about this on their site, that they will only guarantee support the SOAP protocol for 3 years after a version is released. – Larry K Aug 17 '17 at 11:31
  • My statement was not that we support all previous versions, rather that we had customers running (at the time I wrote that) API versions going back to v1.0. Meaning we do not make a habit of forcing customers to upgrade. The limit on support I means "we will fix bugs in that version". Non-support meaning, "sorry you found a bug in that non-supported version, please upgrade to a supported version". It has been a long time since I read it, but I thought support period for API version was 2 years. – pchittum Aug 17 '17 at 15:52
  • Here's the doc from the Metadata API guide: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_support_policy.htm. So you're right that it is 3 years. But note the bit on deprecation. I am not aware of us ever exercising the deprecation policy stated therein. – pchittum Aug 17 '17 at 15:58
0

Have a look at this: https://www.salesforce.com/us/developer/docs/api_rest/Content/dome_versions.htm

Hopefully that answers your question.

Tim
  • 1,373
  • 3
  • 13
  • 27
  • Close but no cigar curl http://na{x}.salesforce.com/services/data/ (where x is my instance number) does return a list of available api versions to my instance (20-33). But does this mean that all these are available for everything hosted on this instance and every object.

    My core question is really what sets the api version?

     – Huw May 13 '15 at 12:10
0

As per @Timothy above. It appears that API versions available is a setting that is largely baked into salesforce and is inimical to my question of 'as switch where you can enable/disable certain versions'.

A closer review of the restforce code seems to show that it is the ruby-on-rails library that is including v26 as the default value:

I'll now initialize my restforce object with the param :api_version set to version v28 so I can describe_layouts.

Therefore, API versions are not something you update on your instance - thus there can be no consequences for doing so.

Hopefully this will serve as a guide for anyone similarly confused when sending requests to the REST API.

Huw
  • 275
  • 4
  • 13