RIPE Atlas API Changes

As announced earlier on RIPE Labs, we are in the process of changing the  RIPE Atlas APIs and transitioning from version 1 (v1) to version 2 (v2). The v1 entry points have been deprecated for a while now, and we plan to remove them altogether at the end of 2016. Here, we'd like to give some assistance to our users on making changes to their programs.

Help with Some Common API Calls

Here are a few hints to convert your v1 API calls to the latest and greatest v2 calls.

We do encourage you to at least browse through the  API v2 Manual to see all the possibilities that the latest API version offers. Also note that this manual is kept up to date for all the changes and additions that are made to the API.

For the full details of the v2 API calls you can consult the API v2 Reference.

Status Checks

Status checks are the one of the simplest API calls to change. The v2 content is actually the same as the v1 content - only the URL needs to change from

 /api/v1/status-checks/MSM_ID/

to

 /api/v2/measurements/MSM_ID/status-check

Measurement results

Acquiring results from measurements have slightly different URIs, but the responses have been unchanged. Since they're lists the URIs have been changed to end in plural nouns, e.g.

 https://atlas.ripe.net/api/v1/measurement/1001/result

has been changed into

 https://atlas.ripe.net/api/v2/measurements/1001/results

The URI for acquiring the latest results from a measurement have been changed from

 https://atlas.ripe.net/api/v1/measurement-latest/1001

to

 https://atlas.ripe.net/api/v2/measurements/1001/latest

API calls that return lists

All API calls that return lists have their URLs changed from a singular noun at the end in v1 to  plural in v2 , e.g https://atlas.ripe.net/api/v1/probe has been changed into  https://atlas.ripe.net/api/v2/probes/ .

Furthermore the structure of root object of the response has changed somewhat:

• The v1 API had an object called "meta" in the root. In v2, all the metadata fields are directly declared within the root object itself. 
• Some of the field names for metadata have changed. Most notably, "total_count" in v1 is now "count" in v2. For more details on the pagination metadata, see the next section on "Crawling Through the API vs. Probe and Measurement Archives".
• The object that holds the data has been renamed from "objects" in v1 to "results" in v2.

  {
  

  "meta": {
  

  "total_count": 19992,
  

  "next" : "/api/v2/probe/?limit=100&offset=100",
  

  "limit": 100,
  

  "offset": 0,
  

  "previous": null
  

  }
  

  ...
  

  }
  

  

 

  {
  

  "total": 19992,
  

  "next": "https://atlas.ripe.net/api/v2/probes/?page=2",
  

  "previous": null,
  

  ...
  

  }
 

Crawling Through the API vs. Probe and Measurement Archives

The pagination (i.e. the structure that's used to get the "next page" of a list of objects) in v2 is slightly different than in v1. This means you need to make minor changes to your code if you depend on fetching a number of objects. As mentioned earlier on the pagination metadata used to be stored in an object called "meta", but has been moved into the root of the response for v2. The "limit" and "offset" metadata field and query-parameters have been replaced by "page" and "page_size" fields and query-parameters. They behave somewhat differently. Read more about it in the API v2 manual .

We'd also like to draw your attention to the existence of daily archives: both measurement archives and probe archives are available historically. In many cases, these are perfectly fine to use. For example, it's much simpler to fetch a single file via FTP to get a list of all known probes rather than crawl through the probe API page by page.

Tools That Can Help You

We've made a variety of tools available that interact with the RIPE Atlas system, including a parsing library, a Python client and a command-line interface. If you're using these tools and wrappers, then you don't need to worry about API version changes.

• The parsing library (called Sagan) can be used in combination with the latest measurement results API as well as the regular measurement results API. This handy library contains a number of parsers that can be used to extract only the relevant data from the full raw data file returned by the API.
• The Python client (called Cousteau) implements Python bindings for the RIPE Atlas API. It can create RIPE Atlas measurements, change the probes of an existing measurement, stop a measurement and fetch its results via HTTP or WebSocket streaming. Newer versions (starting from 1.0 ) of the Cousteau library already use the v2 APIs.
• The command-line interface (called Magellan) lets you do almost everything you can do with the web interface through a CLI instead. Magellan supports the v2 APIs (by relying on Cousteau) from version 1.2.3 onward. 

Documentation

You can find much more information about using the v2 APIs in the documentation .

Outreach

We've already started to contact those who use the v1 APIs heavily and explained how they can make this transition. We'd like to thank all of those who already responded and made the necessary changes (which is virtually everyone we contacted so far). We intend to carry on with this task by periodically contacting the most recent "top five" users.

Some Statistics on API Use

Use of the v2 APIs has been increasing since we started spreading the word in April/May, and has been hovering around 50% of all API calls at the beginning of August. It started to increase significantly when we began contacting the top users of the old API; by now v2 accounts for the vast majority of the queries, about 85% as of last week.

In case you're curious: on 7 September, the top three v1 API users generated more than half of the remaining v1 queries, while the top 10 were responsible for more than 80%.

Feedback

As always, we want to know what you think of RIPE Atlas and our latest developments. We also want to know if you have an interesting use case for RIPE Atlas data that you'd like to share - maybe even on RIPE Labs! Here's how to get in touch:

• Leave a comment about this specific article below
• Subscribe to the RIPE Atlas mailing list for discussions with active users and RIPE Atlas developers: ripe-atlas [at] ripe [dot] net
• If you want to report a bug or problem: atlas [at] ripe [dot] net