How do you specify which version of the REST API to use?

[tiny3001]

We've recently upgraded one of our Splunk Indexers to version 5.0.2

The problem is that this specific indexer was servicing a legacy Ruby on Rails dashboard that created extremely pretty graphs using (I think) the REST API from that specific indexer.

The developer who created it is no longer with us, and my Ruby knowledge is very... limited.

My first instinct was to look for what exactly changed between Splunk 4.3.3 and 5.0.2 and it seems there were changes to a lot of the endpoints. Then I read this in the release notes:

Beginning with this release, the REST API is fully versioned, so that if developers embed the version number in a URL, they are guaranteed a particular endpoint behavior. In addition, REST endpoints optionally can now return JSON instead of XML.

Great, so probably, all I have to do is include the previous version number in the URL and everything should be back to the way it was, right?

Only, I cannot find an example anywhere on how to include the version in the URL.

Can someone provide me with an example?

[sideview]

There's a problem in 5.0 whereby in output mode json you can never get zero results for any search result. Instead of getting zero result rows in the JSON when you should, you'll get a single row that has a single field called "count" with a value of "0". For example, if you had a "| where sessions>10| table username sessions", and then used the username field in another search. In 4.3 your possible results are either a) rows with username and session, or b) no rows. In 5.0 you'll get either a) rows with username and session, or b) exactly one row with only a "count" field.

[tiny3001]

Suspect so yes... especially because the Ruby contains "JSON.parse(resultstring)"

[sideview]

Are you using output_mode=json? I've run into a couple problems there, where behavior in 5.0 was different. Give some more details and I can tell you if it sounds related.

[amrit · Accepted solution]

The API is versioned now, but there's a catch - the base version is v5.0.0. However, there should be very few, if any, breaking changes to the API in 5.0.

Can you share which endpoints your project is using? One way to tell may be to inspect splunkd_access.log and check whether there are any endpoints returning 400, 401, or 404 response codes.

Post 5.0, there have been no breaking API changes, so currently there are no differences based on requested version. For future reference, here's how API versioning works:

Users have three options when making API requests as of Ace/5.0:

• Specify no version, which defaults to the newest endpoint behavior: /services/....
• Specify explicitly that the latest version should be used: /vLatest/services/...
• Specify a version. This can be done with 3 levels of granularity:

1. Specify only a major version. For example, /v5/ will result in the newest 5.x.y.z endpoint behavior being used, but none of the new behavior in 6.0.

2. Also specify a minor version. For example, /v5.1 results in new 5.1.y.z endpoint behavior being used, but none from 5.2 or 6.0.

3. Also specify a bugfix version. For example, /v5.1.2 results in the API behavior being locked to exactly version 5.1.2. Upgrading Splunk to 5.1.3 will not change any API behavior. This will most likely be used when an endpoint bug is discovered, and fixing the bug would require breaking existing consumers of the API.

Note that there granularity stops at the bugfix version number, and that patchfix-level versioning (x.y.z.a) is considered unnecessary and not supported. Suffix strings such as "-beta" are also not supported, as they are of dubious benefit.

[bhavikbhalodia]

Can you please provide us the Splunk Document from where you get the above reference?

[tiny3001]

So this exactly answers my question. I was able to specify versions using /v5/search/jobs, etc, but as amrit said, the catch is that the base version is v5, and I cannot go back to v4 behaviour.

Thanks for the help guys!

[tiny3001]

Endpoints I'm using are:
/search/jobs
/search/jobs/export

That's basically it

[tiny3001]

The moment I'm back in the office tomorrow, I will share which endpoints I'm using!