RIPE Atlas API v2 manual · PDF fileRIPE Atlas APIs Manual This is the manual for the RIPE...

RIPE Atlas API v2 manual

0

1

2

2.1

2.2

2.3

2.4

2.5

2.5.1

2.5.2

2.5.3

2.5.4

2.5.5

2.6

2.6.1

2.6.2

2.6.3

2.7

2.8

2.9

3

3.1

3.1.1

3.1.2

3.1.3

3.1.3.1

3.1.3.2

Table of ContentsIntroduction

Overview

Using the APIs

A Basic Request

Two Types or Resources

Object List Resources

Object Detail Resources

Generic Query Parameters

fields and optional_fields

page and page_size

include

format

more query parameters

Authentication

Anonymous User

API Keys

Session based authentication

Authorization

Result Streams API

Error Messages

Object Documentation

Measurements

Type of Information

Measurement Query Parameters

Create Measurements

Simple Example

The definitions array

RIPE Atlas API Tutorial v2

1

3.1.3.2.1

3.1.3.2.2

3.1.3.3

3.1.3.3.1

3.1.3.4

3.1.3.5

3.1.4

3.1.5

3.1.6

3.1.6.1

3.1.6.2

3.1.6.3

3.1.6.4

3.1.7

3.2

3.2.1

3.2.2

3.3

3.4

4

4.1

5

Base Attributes

Type specific Attributes

The probes array

In Detail

Fields for all Definitions

A Full Example

Stop Measurements

Latest measurements

Status Checks

Simple Example

Complex Example

Monitoring Integration Example

Frequently Asked Questions

My measurements

Probes

Query Parameters

Tags

Participation Requests

Measurement Results

Tips and Tricks

Overcoming the 20,000 objects limit

More Documentation and References

Glossary


2

RIPE Atlas APIs ManualThis is the manual for the RIPE Atlas Application Program Interfaces. It is meant as anintroduction to using these APIs. It is not by any measure as a general introduction toRIPE Atlas.

Alternatively, you can use RIPE Atlas through the web interface.

If you want to make the most of this manual, you should first create a RIPE AccessAccount if you don't already have one.

Different APIsMost of our APIs are REST interfaces over HTTPS. They can be used to get informationabout measurements and probes, and can also be used to create measurements.

We also have a streaming API that continuously delivers new results as they areobtained by the probes using a long-lived HTTPS web-socket connection.


3Introduction

APIs OverviewHere are some resources that will help you get started with the RIPE Atlas APIs.

API Objects

There are three main "objects" that you will encounter in our APIs: Measurements,Probes and Measurement Results. Measurements and Probes are objects that areavailable from the metadata API. Measurement results are available from the ResultsStream API.

Connecting to the APIs

The APIs are primarily designed to be used programmatically through the REST webinterface, over HTTPS using well-known HTTP verbs like GET, POST, etc.

Querying the metadata web API directly in a browser will return a special API webpagethat allows you to browse it.

We also have a number of libraries, most notably Sagan and Cousteau, that allow you tointerface with the APIs from a Python program. We also have a set of command-lineinterface tools available that use the APIs under the hood.

Authenticating to the APIs

First of all, you don't have to authenticate to any of our APIs – you can use them as ananonymous user. You will be able to request all publicly available information, but someinformation is not visible.

To create measurements and to see information about your own probes, you will have toidentify yourself to RIPE Atlas. There are two methods to authenticate.

The first and most useful method from a client program is to use authentication keys.These keys cannot be created using the API; they must be created using the webinterface.

The second method is to log in with your RIPE NCC Access account credentials and usethe session-based cookie in your API requests. This method is primarily used toauthenticate AJAX requests from web browsers. You can create a RIPE NCC Access


4Overview

account here.

More Detailed Information About the APIs

This manual is only an introduction. If you need to look up detailed information, you cango to the API reference. The API reference lists all fields, query parameters and payloadspecifications for most objects.


5Overview

Using the APIsThis section gives an overview of the possibilities when using the RIPE Atlas APIs.

You will see that most of the pages in this section feature a try it button. The actiontriggered by this button will make a real API request and return the response in a box onthe page.

The easiest way to see the API right away is to go to the browsable API root in yourbrowser.


6Using the APIs


7Using the APIs

A basic RequestThe Base URL

The base URL of all calls to the RIPE Atlas APIs for this particular version is https://atlas.ripe.net/api/v2/ . You can append the name of the object type you wantinformation from to form a URL. For example: https://atlas.ripe.net/api/v2/measurements/

A URL that contains information about one object or a series of objects is called aResource.

Note that the API is only served over TLS.

The object part of the URL should be plural and lower case. For example: measurements and probes

About API versioning

The APIs use semantic versioning from version 2 onward. This means that we will:

Update the patch version (2.0.x) whenever we fix bugs in the APIUpdate the minor version (2.x.0) whenever we extend an API without breakingbackwards compatibility.Update the major version (x.0.0) whenever we make backward-incompatiblechanges

After updates for the patch and minor versions, the previous versions will no longer beavailable. After an update of the major version, the previous API will be still available.

Only the major version number is mentioned in the base URL.

Example

An example of a valid URL looks like this:

https://atlas.ripe.net/api/v2/measurements/?page_size=3


8A Basic Request

As you can see, the API returned a list of three measurements.


9A Basic Request

Two Types or ResourcesA RIPE Atlas API can either return a list of objects or a single object in a response.

We will refer to the first type as an Object List Resource. A URL that points to anObject List Resource generally has the form: https://atlas.ripe.net/api/v2/<OBJECTNAME_PLURAL>/

An API resource that returns a single object will be called an Object Detail Resource.An Object Detail Resource URL usually has the form: https://atlas.ripe.net/api/v1/<OBJECTNAME_PLURAL>/<OBJECT_ID>

These will be discussed in more detail in the next two sections.


10Two Types or Resources

Object List ResourcesAn Object List Resource will return one JSON object. This JSON object holds the fields count , next , previous and 'results . This latter field is an array of JSON objects.Its URL will end with the name of the object type. For example: https://atlas.ripe.net/api/v2/measurements/

The results field will hold an array of objects. Each object contains a field id and afield type that, together, are unique identifiers across all the RIPE Atlas APIs.

You can add query parameters to the URI to filter object properties. You can also usequery parameters to add additional fields to the objects, or remove fields from theobjects. An example of a filter query parameter is is_oneoff=true , while an example ofa query parameter that would reduce the fields is fields=id,country_code=gr .

A Resource that holds a request list will always be paginated. This means that theresponse to a single request will be broken down into separate responses if the numberof objects requested exceeds 500. The details of this pagination are all in the count , next and previous fields of the response. The response has a field count that liststhe total number of objects found in RIPE Atlas. This count field will never have avalue higher than 20,000.

For more information on this limit and how to get more than 20,000 results, see this tip.

https://atlas.ripe.net/api/v2/probes/?page=10&sort=id


11Object List Resources

Object detailsAn Object Details Resource returns exactly one JSON object.

Like the List Resource, the object returned from the metadata API has a type and a id field that, together, are unique identifiers across RIPE Atlas.

https://atlas.ripe.net/api/v2/probes/143/


12Object Detail Resources

Generic Query ParametersEvery request to the RIPE Atlas API can be accompanied by one or more queryparameters. This was already shown in the basic request featured.

Some of the available query parameters are specific to a request, most notably queryparameters that are used as filters on Object List Resources. An example of such aquery is:

https://atlas.ripe.net/api/vs/measurements/?status_name=Connected

There are also some query parameters that are available on all list requests and on alldetail requests. Most of these have to do with structuring, formatting and browsing thedata. These generic query parameters will be discussed in the next sections.

A word of warning on query parameters

The RIPE Atlas APIs will silently ignore any unknown query parameters. This means thatusing an invalid query parameter name will return a "regular" response. This behavior isnecessary to accommodate some client programs. For example: The jQuery ajax() method passes in "garbage" query parameters to invalidate server-side caches.


13Generic Query Parameters

The fields and optional_fields Query ParametersEvery request to the RIPE Atlas APIs will always return the fields that constitute theunique identifier for that particular object. Generally that will be id and type . Someoptional fields can also be added to the request. Every other field can be explicitlyremoved.

The query parameters that allow this are the fields and the optional_fields parameters.

fields

Let's start with an example: https://atlas.ripe.net/api/v2/probes/143/?fields=first_connected,status_since will return only the fields first_connected and status_since of the probe with ID 143.

https://atlas.ripe.net/api/v2/probes/143/?fields=first_connected,status_since

Using an empty fields= query parameter only returns the id and type parameterfor each object.

optional_fields

Using the optional_fields query parameter with a comma-separated list of field namesmeans these fields will be appended to every requested object, next to the fields that arealready there by default.

For example, the request https://atlas.ripe.net/api/v2/measurements/2000000/ will not,by default, return the fields participation_requests and probes , mainly because thesefields require extra calls to the back-end database and contain information that is notobviously needed. If you add optional_fields=participation_requests,probes as a queryparameter, however, you will see these two extra fields:


14fields and optional_fields

https://atlas.ripe.net/api/v2/measurements/2000000/?optional_fields=participation_requests,probes


15fields and optional_fields

The page and page_size QueryParametersThe page and page_size query parameters are used in conjunction most of the timeon requests that return object lists. The query parameter page_size allows you to setthe number of objects returned in one page, while page allows you to specify the pagenumber you want to view, based on a specified number or the default page_size of 100.

The APIs use these query parameters themselves to construct links to the next andprevious page of any list of objects. For example, if you request the URL:

https://atlas.ripe.net/api/v1/measurement/2000000/

You'll see that the API returns a next field that contains a link with the queryparameters ?page=2 .

There are some important things to note when using these query parameters:

Values over 500 on the query parameter page_size will be automatically limited to500.The product of the values page_size and page cannot be more than 20,000. Arequest higher than this limit will result in an HTTP error. See this page forinformation on how to overcome this limit.Using the page and page_size parameters is meant to limit the size of theresponse as a convenience for users. Using many requests with small limits will notspeed up (or slow down), the RIPE Atlas APIs. Using many small requests will,however, require more overhead on you network connection in comparison to onebug request to RIPE Atlas.


16page and page_size

The include parameterSome objects contain references to other, related objects from RIPE Atlas. By default,these objects will only be included with their type and ID. The client program could thenconstruct a new request to the RIPE Atlas APIs to get detailed information about thisrelated object.

To reduce the number of requests a client program has to make, you can include thedetailed information on the related object by using the include parameter.

If you toggle the included query parameter, you can see the differences in the way theprobes are included in the response:

https://atlas.ripe.net/api/v2/anchor-measurements/?include=probes


17include

The format parameterThe format query parameter has multiple uses.

The most basic specifies the output format of the response. Available formats are JSON,JSONP, API, TXT and XML. JSON and JSONP will output their respective formats. Thevalue jsonp can be accompanied by a callback query parameter that holds as valuethe JavaScript function to be called as callback. The value txt is used for listresponses. It is mostly useful for very large responses, as it returns the objects line byline, so the client program can use a partial response directly. The value api forces theresponse to be a complete HTML page with browsable links. This is also the defaultformat if you type in a URL in a browser. The default for a request coming from any otherclient is json .

A more advanced use of the format query parameters has the syntax format[<VALUETYPE>]=<OUTPUTTYPE> . Right now, the only value type that we support is datetime . You can specify a datetime output format from values unix , timestamp , json , and iso8601 . The unix and timestamp fields are synonymous and outputdatetimes as UNIX time stamps (i.e. seconds from epoch). The other options - json and iso8601 - are also synonymous and will output all datetimes as the humanreadable ECMA-262 format: YYYY-MM-DDTHH:MM:ss.

Please note that right now we output ECMA-262 datetimes implicitly in the UTCtimezone.


18format

More Query Parametersmine=true

If you are logged in to RIPE Atlas, you can see objects that you own by passing thequery parameter mine=true for measurement objects.

sort

This query parameter will order the results by the field name that is given as the value,e.g. sort=-id .

key

The key parameter allows you to authenticate and authorise yourself to the RIPE AtlasAPIs. The actual key can be generated by you if you have a RIPE Atlas account, or ifsomebody gave you one. You can learn more on this parameter, authentication andauthorisation here.


19more query parameters

AuthenticationAs mentioned in the overview, there are two methods to authenticate to RIPE Atlas andyou can use most of our APIs unauthenticated (i.e. as an anonymous user).

The two authentication methods are:

Use an API key. This is the preferred way of authentication to the APIs.Use a session-based cookie. This is primarily used for client-side JavaScript in webbrowsers.

The next sections will discuss this in detail.


20Authentication

Anonymous UserYou don't have to authenticate to RIPE Atlas at all. You can simply send a request andyou will get a response. In this case, you are using the API as an anonymous user.

If an anonymous user does not have the right permissions to view the resourcerequested, the response will be a HTTP 403 error with a JSON object holding the errormessage.

Furthermore, some objects in the response will be obfuscated or left out completely foranonymous users. These restrictions are mainly invoked out of privacy concerns for thepeople and organisations hosting the probes.

Obfuscation of Geographical Data

Probe locations are obfuscated for all RIPE Atlas users. The obfuscation consists ofdropping some accuracy from the geographical coordinates as supplied by the probeowners and then spreading them a bit to avoid having multiple overlapping probes. Thelocation as provided by the API will be within 80 to 400 metres of the actual locationknown to RIPE Atlas.

Restricted Fields

The probes' IP addresses are only shown if the probe is public. If the probe is non-public, then the IP address is only available to the probe owner. If the IP prefixes areknown to RIPE Atlas, they will be visible to all users.

Public Objects

Both Probe and Measurement objects can be public. If so, they will have a field called is_public set to "true". Anonymous users can only see public objects.

https://atlas.ripe.net/api/v1/1/


21Anonymous User


22Anonymous User

API KeysThe preferred and most convenient method to authenticate to RIPE Atlas is to use APIkeys. API keys can be created via the web interface and there is documentation on howto do this. Note that you need a RIPE NCC Access account, which you can create here ifyou don't already have one.

You can assign permissions to API keys and you can share them with other people.Please keep in mind, though, that the RIPE Atlas keys are intended as secret keys.This means that an API key is the only thing needed to elevate the permissions of anarbitrary program or user to the level given by that particular API key.

The user who created the API key is referred to by RIPE Atlas as the creator of the key.Key permissions can never be greater than those of the creator. This also means thatkey permissions can be lowered when the creator's permissions are lowered.

API keys are always used in the RIPE Atlas APIs by passing them in as queryparameters in a web request:

https://atlas.ripe.net/api/v1/measurement/?key=1233-3434-4556-565


23API Keys

Session-based AuthenticationSession-based authentication is primarily used for Ajax calls in client-side JavaScriptapplications in browsers.

Showing a session-based API authentication in detail is outside the scope of thismanual.

Note that RIPE Atlas has cross-site request forgery (CSRF) protection and same-originpolicy on its APIs for session-based requests.


24Session based authentication

AuthorisationAn authenticated API request can be authorised for one or multiple of the followingactions:

Request full details of non-public objects, including IP addressesCreate a measurement requestStop a measurementAdd or remove probes from a measurement

Please note that geographic locations will always be obfuscated. See here for moredetails.

If you're not using a session-based authentication, each of these actions require a keythat hold the required permission for that particular action. A key can only hold onepermission, but some permissions imply accumulated permissions. For example, a keywith create-measurement permission can also be used to view measurements.

More information on viewing your own measurements is available here.


25Authorization

RIPE Atlas Result StreamsRIPE Atlas has been providing downloadable results since the very beginning of theproject. This works well if you know what time frame you're interested in, and want to getthe data collected during that period.

The streaming data service allows you to tap into the real-time data flow of all thecollected public results. Every time our system receives a data point or a probeconnectivity event occurs, it's also delivered to the clients who are "tuned in" to thatresult stream. This feature is implemented using WebSockets.

HighlightsThis service is in prototype status. We're observing how our system reacts to thestreams provided to users in order to evaluate the feasibility and usefulness of aproduction service.Streaming uses the Socket.IO protocol over WebSockets for real-time event-basedcommunication.You can only subscribe ("tune in") to results delivered by public measurements.You can subscribe to the connectivity events of any probe.We're inviting the community to check out the gallery of visualisations provided bythe RIPE Atlas team and our users as soon as it becomes available, and to comeup with new visualisations and/or to enhance existing ones.

It is also possible to stream historic events at the rate at which they occurred, or with aspeed-up factor.

Basic ExamplesThe service address for the stream is http://atlas-stream.ripe.net.

The following examples will show how to connect to streaming for the various streamtypes.

Stream type: result


26Result Streams API

When stream_type is set to "result", the client will receive measurement results.

<script src="https://atlas-stream.ripe.net/socket.io.js"></script><script>

// Create a connection (it can be also http on port 80) var socket = io("https://atlas-stream.ripe.net:443", { path : "/stream/socket.io" });

// Subscribe to results coming from all the probes involved in the measurement 1791207 socket.emit("atlas_subscribe", { stream_type: "result", msm: 1791207 });

// Declare a callback to be executed when a measurement result is received socket.on("atlas_result", function(result){ console.log("I received ", result); });

</script>

Stream type: probestatus

When stream_type is set to "probestatus", the client will receive probe connection anddisconnection events.


// Create a connection var socket = io("https://atlas-stream.ripe.net:443", { path : "/stream/socket.io" });

// Subscribe to the connection events of the probe 22527 socket.emit("atlas_subscribe", { stream_type: "probestatus", prb: 22527 });

// Declare a callback to be executed when a probe connection event is received socket.on("atlas_probestatus", function(status){ console.log("I received ", status); });

</script>

Stream type: metadata

When stream_type is set to "metadata", the client will receive measurement metadataevery time a measurement is created or edited.




// Create a connection var socket = io("https://atlas-stream.ripe.net:443", { path : "/stream/socket.io" });

// Subscribe to measurement creation/edit events targeting a specific prefix socket.emit("atlas_subscribe", { stream_type: "metadata", destinationPrefix: "2001:67c:2e8::/48" });

// Declare a callback to be executed when an event is received socket.on("atlas_metadata", function(metadata){ console.log("I received ", metadata); });

</script>

ParametersBelow we describe all the parameters available in the streaming system.

Subscription parameters

The following parameters can be used to specify what you want to receive on thechannel. Some of these parameters are common among the various stream_type;others are more specific. See the tables below for more details.

Common parameters (in addition to stream_type)



Name Description

prb A specific probe ID. If you don't set this parameter,you will receive results from all the probes.

acceptedFieldsA list of accepted field names; the messages will bepruned server side. If you don't set this parameteryou will receive all the fields.

enrichProbesIf you want to enrich the information received withthe "probestatus" stream about the probes (e.g. lat,long), set this option to true.

equalsTo

Allows filtering by values. E.g. with {status:"connected", asn: "3333|4444"} you will receive allthe messages with a connected status for ASN3333and ASN4444.

lessThanAllows filtering by values. E.g. with {valueX: 15} youwill receive all the messages with a valueX less than15.

greaterThanAllows filtering by values. E.g. with {valueX: 15} youwill receive all the messages with a valueX greaterthan 15.

Parameters for "result" stream_type



Name Description

msm A specific measurement ID.

type Streams all the results of the specified type (ping,traceroute, DNS, SSL, HTTP, NTP).

sourceAddress Streams all the results coming from a probe with thespecified address.

sourcePrefix Streams all the results coming from a probe with anaddress in the specified prefix.

destinationAddress Streams all the results measuring the specifiedaddress.

destinationPrefix Streams all the results measuring an address in thespecified prefix.

sendBacklog

Immediately fetches the last few minutes of resultsfor a specific measurement ID. Mostly intended tocover the gap between the last available data in theREST API and the currently streamed results, and torecover results that might have been missed duringbrief disconnections.

Parameters for playing historic events

You can replay events that have happened in the past, and the timing will resemble theactual timing of the event as it happened. Note:

You cannot replay metadata.

You can replay only specific measurement IDs, and optionally filter by probe.Additional parameters will be ignored.

You cannot have multiple playbacks for the same measurement at the same time(e.g. a view of an event one year ago and one month ago running concurrently). Ifyou subscribe to a new probe for an already running measurement, you will simplystart seeing results for that probe from the already running measurement stream.



Name Description

startTime Start time (seconds since 1970) of the event to replay.

endTime(optional)

End time (seconds since 1970) of the event to replay. For stoppedmeasurements, this defaults to the stop time. For othermeasurements, this defaults to the present time.

speed(optional)

The speed-up factor (float). Defaults to 1.0 (original speed). There isa limit to the maximum speed that is determined by the number ofparticipants for the given measurement.

Example:


// Do something when we get a connection/disconnection socket.on("atlas_probestatus", function(status){ console.log("I received ", status); });

// Stream all connection/disconnection events from midnight on 2015-3-18 socket.emit("atlas_subscribe", { stream_type: "probestatus", startTime: 1426633200 });

</script>

Events you can tune into



Name Description

connect When the connection is established

disconnect When the connection is terminated

atlas_error Error messages coming from the stream service

atlas_result Measurement results of a "result" subscription

atlas_metadata Measurement metadata of a "metadata" subscription

atlas_probestatus Connection and disconnection event of a"probestatus" subscription

atlas_subscribed When a subscription to a channel is successful

atlas_unsubscribed When the client has been unsubscribed from achannel

atlas_replay_finishedWhen replay of a historic stream has reached theend, according to the user-given stopTime, the actualmeasurement stop time, or the present time

Events you can emit

Name Description

atlas_subscribe To subscribe to a channel (parameters needed)

atlas_unsubscribe To unsubscribe from a channel (parameters needed)

You can also check out the source code of the visualisations below.

Available VisualisationsVisualising which DNS root instance a probe ends up on: DNS root instancesVisualising probe connections and disconnections: Probeconnections/disconnectionsReal-time latency graphs (against AS3333): Real-time latency graphs



Error MessagesIn case of an error, the RIPE Atlas APIs will return the error as a HTTP status code anda JSON response that describes the error as faithfully as possible.

The JSON response is crafted according to the jsonapi specification.

Sometimes you will get an extra code field that has an integer value. This is an errorcode specific to RIPE Atlas.

These are the codes you might encounter:


33Error Messages

Code Message Explanation

100

This server onlyacceptsapplication/JSONcontent types.

The REST server is only capable of readingJSON data from your requests.

101

Your JSONPOST requestappears to bemalformed.

Make sure your JSON data is properly formatted.Use an online parser if necessary.

102Invalid input.Please check thedocumentation.

Some of the basic elements of a POST aremissing. Make sure you've supplied a value for definitions and probes , as well as values for description , type , and af in each definitionand requested , type and value in each proberequest.

103

You are notpermitted to runmore than %sconcurrentmeasurements.

Users are limited to a finite number ofmeasurements that they can execute. Attempts toexceed this limit will result in this message.

104 (Variable)

This is a blanket error code assigned to any errorthat prevents your measurement from running(over and above the others stated here). Themessage changes based on what's gone wrong,but examples include exceeding the limit ofmeasurements targetting a particular domain, orspecifying an excessive number of packets in aping request.

200

Thatmeasurementcannot bestopped.

This error is raised when you try to stop ameasurement that has already been stopped.


34Error Messages

Object DocumentationThis section describes the objects Measurement , Measurement Result , Probe and Participation Request in more detail.


35Object Documentation

MeasurementsA Measurement in the context of the RIPE Atlas APIs is an object holding informationabout one measurement (called a "one-off" measurement) or a series of measurementsperformed by one or more probes on the RIPE Atlas network. The response of a singlemeasurement performed by a single probe is called a measurement result .

If we look at the information returned in more detail we can discern:

Measurement metadata: the ID and the measurement type and information on theselected probes, including whether this is a public measurement.Attributes of the measurement specification, i.e. the attributes that a probe needs tostart performing measurements.Status information of the measurement. E.g. Is it running? When was it started?,etc.

The next sections will describe the details of these different types of information.


36Measurements

Type of InformationFirst, let's ask the RIPE Atlas API for a measurement:

https://atlas.ripe.net/api/v2/measurements/2000000

Metadata

A Measurement object holds information about the measurement itself. First it holds thefields id and the type that, together, provide a unique identifier for the measurementobject. Examples of measurement types are HTTP and Traceroute .

The participation requests array holds a list of participation request objects, whichdescribe the probe selection criteria that were made for this measurement. You can readmore about the particapation request object here.

Please note that this is not the same as the actual probes that are appointed to ameasurement by RIPE Atlas. The latter would be part of the status information of themeasurement in a object called probes . See below.

Finally, there are some fields that describe some of the measurement's generalproperties. They are is_public and result , a URL that points to the result of themeasurements as performed by the selected probes.

The Measurement Specification

The Measurement object holds the measurement's settings, called the "measurementspecification" in RIPE Atlas terminology. This specification is a mixture of baseattributes, available for all types of measurements and type-specific attributes. Examplesof such attributes are packets , method or interval .

The measurement specification is the object that is sent to a specific probe to perform itsmeasurement.

You can see an exhaustive list of all measurement specification attributes for all kinds ofmeasurements here.


37Type of Information

Status Information

A Measurement object also holds the information about the time series of measurementsto be performed by the probes, like the start and stop time of the measurements and thelink to the streaming API resource that holds the result of the performed measurements.

A Measurement object also holds information about the status of the measurement, e.g.if it is currently running, stopped, etc.

Finally, the Measurement object holds information about the actual probes used in themeasurement. This information is in an object called probes . This is an optional field,which can be enabled by using the optional_fields=probes query parameter.


38Type of Information

Measurement Query ParametersMost of the generic query parameters apply to requests for measurement objects. Youcan use page and page_size to manipulate the number of objects and the pagination;you can use fields and optional_fields to set the fields you want in the response,and so on.

See here for more information on these.

Field Filters

You can filter on most responses that are included in a typical response formeasurement objects. Fields like id , target_name , etc. can be used directly as filters:

https://atlas.ripe.net/api/v2/measurements/?id=2000000

For some fields, it is also possible to enter a range filter, i.e. a filter that selects a rangespecified by a list, or by a lower and an upper limit.

These range filters have special syntax for their query parameters.

The list range filter uses the syntax ?<FIELDNAME>__in=item1,item2 . An example is:

https://atlas.ripe.net/api/v2/measurements/?id__in=2000000,2000001,2000002

The limit range filter uses the syntax appended with either __gte , __gt , __lte or __lt . As mentioned earlier on gt and gte refer to greater than and greater thanor equal . You can combine multiple query parameters to set upper and lower limits:

https://atlas.ripe.net/api/v2/measurements/?id__gte=2000000&id__lte=2000010

Query Parameters for probes and


39Measurement Query Parameters

Query Parameters for probes and participation_requests

The fields probes and participation_requests are not included by default in a requestfor one or more measurements. You can include them, however, by specifying either fields= , without a value, or by specifying them as a value, i.e. fields=probes . In thelatter case, you would only get back the specified field.

API Reference

A full list of all available fields and query parameters is available here.


40Measurement Query Parameters

Creating MeasurementsMeasurement creation is managed based on the premise of having to submit as littleinformation as possible while still obtaining something useful. With that said, even thesimplest measurement requires a rather large amount of information to initiate things.You will need to compose a measurement definition that has at least the type , af , description and target fields, as well as a probes object telling us which probes youwant to use for the measurement.

If you omit the start_time , we assume you want it started right away; if you don't setthe is_oneoff flag, we assume it must be a regular measurement, and so on.

You will also have to use a valid key with the right permissions. See the section onkeys for more information.

This section of the manual doesn't contain a try-it-out box, because it would create realmeasurements on the RIPE Atlas system and place unnecessary burden on thenetwork. In addition, you would need a valid key.

If you do want to create measurements, you must use a tool that is able to send POSTrequests with a payload to RIPE Atlas. Three such tools are postman (a plug-in forChrome), HttpRequester (a plugin for Firefox) and cURL (a command-line tool).

Structure

Our measurement REST API uses a JSON payload with a POST verb to create newmeasurements.

You can fill in one or more measurement definitions , one or more probes objects,and some fields that are applicable to all measurements you want to create.

The Response

The response to any successful POST request will return an object that has one fieldcalled measurements . This field holds an array that contains the IDs of the createdmeasurements. The array reflects the order in which they were specified in the definitions list of you request.


41Create Measurements

Simple ExampleLet's begin with an example. Assume we want to create a simple ping measurementfrom 50 probes anywhere in the world to ripe.net .

Here's how to do this in cURL:

This is what it looks like in Postman:



ResponseIf you have filled out everything correctly, you will get a response like this:

{"measurements": [<SOME_MEASUREMENT_ID>]}

If you didn't use the right key, or no key at all, you will get an error:

{"error":{"status":403,"code":104,"detail":"Authentication credentials were notprovided.","title":"Forbidden"}}

In this case, you may want to check keys documentation.

If you made a mistake in the entry of the payload, you will get the following error:

{"error":{"status":400,"code":104,"detail":"Invalid input. Please check the documentation.","title":"Bad Request"}}

In this case, check your entry carefully and try again.

Now let's take a look at our request in more detail.

The Payload for the POST RequestLet's take another look at the payload we sent with the POST request:

{ "definitions": [ { "target": "ripe.net", "description": "My First Measurement", "type": "ping", "af": 4 } ], "probes": [ { "requested": 50, "type": "area", "value": "WW" } ]}



Basically, each request has two objects: definitions and probes , along with somegeneral fields that apply to all measurement definitions in the request. In our example wedidn't use any of those general fields.

In the next sections we will discuss these objects and fields.



The definitions ArrayThe definitions array holds single objects, which we will refer to as measurementdefinitions.

A measurement definition has a similar structure to a measurement specification . The measurement specification , as you might recall, is the collection of measurementsettings that a probe needs to perform a measurement. There are some base attributesand some type-specific attributes in the specification.

A measurement definition is a sub-set of the measurement specification. There aresome required fields, but most are optional. RIPE Atlas will fill out the missing fields withdefaults for all non-required fields. Which fields are required differs per measurementtype.

These are the required fields for all measurement types:

description : An arbitrary string you will use to refer to this measurement. type : One of ping , traceroute , dns , sslcert or ntp af : The address family. It must be either 4 or 6 .

The target field denotes the target of a measurement and is special because it isrequired for all measurement types except DNS measurements.



Base AttributesA measurement definition contains a few base properties, and a myriad of type-specificoptions. For example, while all definitions have an af property, only traceroute measurements have a paris property.

Base Properties

These properties are available for all measurement types.

Name Description Default Required? PriceModifier

descriptionThe name yougive thismeasurement.

YES

afThe addressfamily. Must beeither 4 or 6.

YES

type

The type ofmeasurementyou'reattempting tocreate. Must beone of: ping,traceroute,DNS, SSL orNTP.

YES

resolve_on_probe

Set to "true" ifyou want theprobe toresolve yourtarget insteadof the RIPEAtlas servers.

false

is_oneoff

Set this to"true" to makethismeasurement aone-off.

false

Make this



is_publicmeasurementpublic, so otherpeople can seethe results.

true

interval

In normal (notone-off)measurements,this valuerepresents thenumber ofsecondsbetweenmeasurementsby a singleprobe. Notethat whileinterval isdefined foreachmeasurementtype, thedefault varies,so check theappropriatesection belowfor the defaultvalues.

changeswithtype



Type Specific AttributesAside from the base attributes that must be present in any request to create ameasurement, there are specific attributes required for each measurement type.

We are mentioning only the required fields for every type. An exhaustive reference of allattributes that can be used are listed here.

DNSRequired attributes:

Name Description

query_class Must be either "IN" or "CHAOS"

query_type Varies with the query_class

query_argument The argument part of the query used in the measurement

NOTE: For privacy reasons, when use_probe_resolver is set to "true", the attribute set_rd_bit is silently set to "true".

For the complete reference, see here.

PingRequired attributes:

Name Description

target The FQDN (if it was requested) or the IP address of the target of thismeasurement

For the complete reference, see here.

Traceroute, SSL Certificate, HTTP and NTP



Required attributes:

Name Description

target The FQDN (if it was requested) or the IP address of the target of thismeasurement

For complete references for these measurement types, see here.



The probes ArrayThis section describes how to select probes to use in measurements based on theirlocation. For our basic case, there's only one request: 50 probes located anywhere in theworld.

requested : The number of probes you want from the given region. type : The type of request. It can be one of area , country , prefix , asn , probes or msm . value : The lookup used against the given type . This is explained in more detailbelow, but for our reasons, let's just work with the fact that WW means worldwide.

Based on the above, the API will create a ping measurement hitting the first IPv4 address found at ripe.net , using 50 probes from various points all over the globe.



The probes Array in DetailThe probes array holds single objects.

A Single probes ObjectBasically, there are six types of requests: area , country , prefix , asn , probes and msm . In each case, you'll be stating how many probes of that type you'd like to use( requested ) and what subsection of that type you're looking at ( value ). In addition, youcan optionally further restrict each request using probe tags. We'll go over the requesttypes one by one.

Area

For our purposes, the world is broken up into five arbitrary geographical areas:

WW (Worldwide) West

North-Central

South-Central

North-East

South-East

Country

If you want to request probes by country, specify the ISO two-letter country code here.For example, you would use CA for Canada, NL for the Netherlands, and KR forSouth Korea.

Prefix

This is an IP prefix. For example:



"probes": [ { "requested": 5, "type": "prefix", "value": "193.3.6.0/8" }]

ASN

For ASNs, just the number is sufficient. For example:

"probes": [ { "requested": 5, "type": "asn", "value": 3333 }]

Probes

Probes can be explicitly requested by requesting type: "probe" and specifying acomma-separated list of integers as the value :

"probes": [ { "requested": 3, "type": "probes", "value": "1,2,3" }]

Measurement ( msm )

Finally, if you want to use the same probes as in a past measurement, you can simplyspecify the previous measurement ID in the value field:



"probes": [ { "requested": 1, "type": "msm", "value": 1000002 }]

Additional: Probe Tags

Any of the above request types can be further restricted based on probe tags. This isachieved by specifying an optional "tags" item which may contain one or both of "include" (a list of tags to require) and "exclude" (a list of tags to prohibit).

For example, to request 10 probes from anywhere in the world that are in a data centre,and do have working IPv4 but do not have working IPv6:

"probes": [ { "requested": 10, "type": "area", "value": "WW" "tags": { "include": ["datacentre", "system-ipv4-works"], "exclude": ["system-ipv6-works"] } }]

The probes and participation request Objects

The probes array will be turned into a participation request object by RIPE Atlasafter the measurement has been created. It will also have its own ID and URL where youcan view it. You can read more about the participation object here.



Fields for all DefinitionsThere are some fields in the POST payload that are applicable to all definitions in therequest.

The times Field

As we mentioned earlier, the measurement API supports a general field: times . Thisfield is a set of values dictating the start and end times for all measurements you'respecifying in the request. In other words, if you send a single request to create two ping measurements targeting ripe.net , you can use times to specify when you'dlike both measurements to start and finish.

If you want to have measurements start or stop at different times, you must define themin separate API requests.

The bill_to Field

All measurements you create come at a cost. The cost of a measurement is estimatedby RIPE Atlas in advance based on the number of probes, the interval and the start andstop times. However, the actual billing will be done when the measurements areperformed by the probes. Normally the cost of a measurement will be billed to your ownaccount.

The bill_to field allows you to charge the cost of a measurement to another user. Ofcourse, you cannot charge random users. The user you want to charge will have to addyou to their list of users that are allowed to charge their account.

You can read more about RIPE Atlas credits here.



A Full ExampleThis following request payload is an example of the features we've discussed:

{ "definitions": [ { "target": "www.ripe.net", "description": "My Complex Measurement", "type": "traceroute", "af": 6, "resolve_on_probe": true, "is_public": true, "packets": 16, "protocol": "ICMP", "paris": 99, "firsthop": 30, "interval": 1800, "is_oneoff": false }, { "target": "www.ripe.net", "description": "My Complex Measurement", "type": "ping", "af": 4, "resolve_on_probe": false, "is_public": false, } ], "probes": [ { "requested": 10, "type": "area", "value": "WW" }, { "requested": 5, "type": "country", "value": "GR" }, { "requested": 5, "type": "country", "value": "CA" }, { "requested": 3,



"type": "probes", "value": [55,19,252] }, { "requested": 1, "type": "udm", "value": 1000002 } ], "start_time": 1461807395, "stop_time": "2018-01-01T12:00:00Z", "is_oneoff": true }

Note that this example has multiple measurement definitions, multiple probe participationrequests and some defaults set outside the definitions section. So, the firstmeasurement that will be created has is_oneoff set to false - by means of setting itdirectly in the definition. The second measurement will have is_oneoff set to true ,because it will take the default that was set in the root of the payload.



Stop MeasurementsMeasurements can be stopped by sending a DELETE verb to the URL of themeasurement you want to stop. For example, if you want to stop the measurement with msm_id 2034345, you will have to send a DELETE verb to: https://atlas.ripe.net/api/v1/measurement/2034305 .

You can only stop measurements that you've created yourself or that you have an APIkey for (and which has permissions to stop measurements). In the first case, you willhave to be logged in with a session-based cookie.


58Stop Measurements

Latest Measurement Results API

LocationThe latest measurement results API can be found here:

https://atlas.ripe.net/api/v2/measurements/2000000/latest/?probe_ids=10008

Much like the other similar API URLs, this one works by inserting a single measurementID to return JSON data.

Output FormatThe output format is only slightly different from what you'd expect from the standardmeasurement result API call. Rather than simply dumping every result as a list, it returnsa series of key/value pairs in the format:

{ probe_id: [<result>], probe_id: [<result>], ...}

This allows you to easily fetch the latest result from probe 123 , for example, by using:

my_data["123"][0]

VersioningIn case you're wondering why the format is probe_id: [<result>] and not simply probe_id: <result> , this is due to the fact that you can request up to 10 previous resultvalues for every probe by specifying versions=n , where n is a number between 1-10:


59Latest measurements

https://atlas.ripe.net/api/v1/measurement-latest/<measurement-id>/?versions=1{ probe_id: [<result>], probe_id: [<result>], ...}

https://atlas.ripe.net/api/v1/measurement-latest/<measurement-id>/?versions=2{ probe_id: [<result>, <result>], probe_id: [<result>, <result>], ...}

The versions will always be returned in reverse chronological order, so requesting my_data["123"][0] will always be the most recent result, and my_data["123"][1] , thesecond-most recent.

FilteringYou can also do basic filtration by probe id simply by using probe_ids=probe_id,probe_id as query parameters.

Note, however, that if you specify a probe ID that is not part of the measurement, you'llsimply get back an empty set.

CachingPresently, the API is cached at 5 minutes, i.e. the information returned from this URLmight be 5 minutes behind the actual state.


60Latest measurements

Status ChecksStatus checks let you turn a measurement into a basis for an alert, allowing you to usemeasurements to gauge the health of your network in a variety of ways.

We'll be covering both the simple method for setting up status checks that uses thedefault options, and a more complex example that makes use of the variouscustomisations available.

Quick StartIf you just want to get started using status checks, you simply need to do the following:

1. Create a RIPE Atlas ping measurement using either the website or the API.You may use up to 1,024 probes.Note the newly-created measurement ID

2. Go to: https://atlas.ripe.net/api/v2/<measurement-id>/status-checks/ where <measurement-id> is the ID from your newly created measurement. If themeasurement in question is not public, you'll need to include an API ?key= argument.

3. Go to the URL again later to check whether anything has changed.4. Define your alerts accordingly.


61Status Checks

A Simple ExampleLet's say that your website, www.example.com , is hosted on servers in Europe and NorthAmerica. You're interested in availability and response time, so you create a RIPE Atlasping measurement from five locations around the globe and begin seeing results comingback that look something like this:

Rotterdam, Netherlands: id: 123, rtt: 9ms Athens, Greece: id: 234, rtt: 12ms Vancouver, Canada: id: 345, rtt: 13ms São Paulo, Brazil: id: 456, rtt: 55ms Brisbane, Australia: id: 567, rtt: 312ms

The ID for your new measurement is 123456789 , so you can get basic information aboutyour measurement by querying this URL:

https://atlas.ripe.net/api/v1/measurement/123456789/

The new status checks system is can be found at a similar URL:

https://atlas.ripe.net/api/v2/123456789/status-checks/```

Querying this URL alone should give you basic dashboard values for your server, whichis enough for you to plug into a monitoring engine like Nagios. The output should looksomething like this:


62Status Checks

# RequestGET https://atlas.ripe.net/api/v2/status-checks/123456789/

# ResponseHTTP/1.1 200 OKDate: Tue, 29 Oct 2013 14:37:37 GMTX-RIPE-Atlas-Global-Alert: 0Content-Type: text/plainCache-Control: no-cache

{ "global_alert": false, "probes": { "123": { "alert": false, "last": 107.296, "last_packet_loss": 0.0, "source": "Country: NL" }, "234": { "alert": false, "last": 14.152, "last_packet_loss": 0.0, "source": "Country: GR" }, "345": { "alert": false, "last": 9.328, "last_packet_loss": 0.0, "source": "Country: CA" }, "456": { "alert": false, "last": 21.761, "last_packet_loss": 0.0, "source": "Country: BR" }, "567": { "alert": false, "last": 28.281, "last_packet_loss": 0.0, "source": "Country: AU" }}

Note that in the case of every probe above, alert is set to false . This is becauseyour network is presently healthy. If, however, connectivity between your server andBrisbane, Australia were to degrade suddenly, for example, the output might looksomething like this:


63Status Checks

# RequestGET https://atlas.ripe.net/api/v2/measurements/123456789/status-check/

# ResponseHTTP/1.1 200 OKDate: Tue, 29 Oct 2013 14:37:37 GMTX-RIPE-Atlas-Global-Alert: 1Content-Type: text/plainCache-Control: no-cache

{ "global_alert": true, "probes": { "123": { "alert": false, "last": 107.296, "last_packet_loss": 0.0, "source": "Country: NL" }, "234": { "alert": false, "last": 14.152, "last_packet_loss": 0.0, "source": "Country: GR" }, "345": { "alert": false, "last": 9.328, "last_packet_loss": 0.0, "source": "Country: CA" }, "456": { "alert": false, "last": 21.761, "last_packet_loss": 0.0, "source": "Country: BR" }, "567": { "alert": true, "alert_reasons": [ "loss" ], "all": [ null, null, null ] "last": null, "last_packet_loss": 100.0, "source": "Country: AU" }


64Status Checks

}}

Note that probe 567 (the ID for the probe that you're using in Brisbane) has somehowlost the ability to ping your server. This has resulted in the following changes to theoutput of your status check:

The last property (the last attempt to ping your server) has a null valueThe last_packet_loss value is set to 100 %As the last attempt could not get even one packet through, the alert property wasset to true As one of the probes has now triggered an alert, the global_alert property is set to true

The X-RIPE-Atlas-Global-Alert header is set to 1 Two additional values were added to the probe definition in question: all and alert_reasons :

all is a list of all packet results used to calculate last . There will be moreexplanation about this later. alert_reasons is a list of reasons why this alert was triggered. Typically thiswill only have one value: loss , but as we'll see later on, it may also contain latency .

The idea is to have your monitoring software parse this output and act accordingly. Howyou parse it is up to you. A simple use case would be to simply grep the output for global_alert":true and trigger your alerts based on that, while a more nuancedexample might parse the JSON and look for values relevant to different users to pagethe appropriate contact.

If you're not keen on parsing the output, or want to save bandwidth by using a simplertest, we also allow you to abuse the HTTP response code system by setting the flag change_http_status=1 . In this case, the above response would change to the following:

# RequestHEAD https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?change_http_status=1

# ResponseHTTP/1.1 418 UNKNOWN STATUS CODEDate: Tue, 29 Oct 2013 14:37:37 GMTX-RIPE-Atlas-Global-Alert: 1Content-Type: text/plainCache-Control: no-cache


65Status Checks

Note that the only HTTP codes currently in use are 200 and 418. There are noplans to expand the abuse of the HTTP status code system at present, as thiswould make it difficult to indicate whether there is a problem with themeasurement in question, or the status check system itself.

With these sorts of changes, you can write server-side scripts to capture and parse theJSON output, or just note the HTTP response code and take whatever action you see fit.To use Nagios as an example, you could use the check_http script to alert if the HTTPresponse is anything other than 200. There's no need to write any custom code if youdon't want to.


66Status Checks

A Complex ExampleThe simple example above should be good enough for most people, but if you're dealingwith a large subset of probes (we support up to 1024), or if you're interested incomparing the current RTT value to past values, then this section is for you.

You can control how the alerts are triggered based on a few arguments in the URL:

Argument Default Description

max_packet_loss 75 The acceptable percentage packet loss perprobe

show_all false Show all RTT responses. The default is toonly show all responses for alerting probes

permitted_total_alerts 0The total number of probes you wouldpermit to respond with an alert before aglobal alert is issued

lookback 1The total number of measurement resultsto compare to generate a median RTTvalue.

median_rtt_threshold N/A

The threshold at which an alert should beissued when you compare the latest RTTvalue to the median values (based on thelookback)

These arguments can be combined to give interesting results, so we'll break them downone-by-one and then give you some examples of combinations and the resulting output.

max_packet_loss

By default, we don't set alert: true unless the packet loss percentage exceeds 75%. Ifyou'd like to adjust this threshold, you can pass max_packet_loss to the URL. Expandingon our simple example above, this request would require that all packets be lost beforean alert will be set on a probe:

https://atlas.ripe.net/api/v2/123456789/status-check/?max_packet_loss=95


67Status Checks

Note however that if you set max_packet_loss to 100, no alert will ever be set for lostpackets.

Similarly, you can make the check more sensitive by tweaking the max_packet_loss value downward:

https://atlas.ripe.net/api/v2/123456789/status-check/?max_packet_loss=0

This would set an alert if even one packet was lost.

show_all

In the simple example, the sample output listed only basic probe information:

# RequestGET https://atlas.ripe.net/api/v2/measurements/123456789/status-check/

# Response..."234": { "alert": false, "last": 14.152, "last_packet_loss": 0.0, "source": "Country: GR"},...

If ever there is an alert triggered though, the all attribute is included so that you cansee further details:


68Status Checks

# RequestGET https://atlas.ripe.net/api/v2/measurements/123456789/status-checks/

# Response..."234": { "alert": true, "alert_reasons": [ "loss" ], "all": [ null, null, null ] "last": null, "last_packet_loss": 100.0, "source": "Country: GR"},...

By setting show_all , you're asking the server to always include the all attribute in theoutput, regardless of whether or not there's an alert issued, so you'd change the outputof an error-free result to:

# RequestGET https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?show_all=1

# Response..."234": { "alert": false, "all": [ 12.123, 14.152, 17.321 ] "last": 14.152, "last_packet_loss": 0.0, "source": "Country: GR"},...

permitted_total_alerts


69Status Checks

By default, we assume that one probe failing to meet expected thresholds is cause foralarm. If you feel this is too sensitive, you can increase this value. This won't change the alert value for each probe, but it will determine whether or not global_alert will beset to true , and if change_http_status is set to 1 , the HTTP status will be changed to 418 .

The following will allow for a maximum of 3 probes to alert before the global alert is set:

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?permitted_total_alerts=3

lookback and median_rtt_threshold

Sometimes the current median RTT isn't enough information with which to make an alertdecision. Sometimes, you need a little history to determine whether an alert iswarranted. This is where lookback and median_rtt_threshold come in.

Let's use our example again. Say that you've been running this measurement for a fewhours now and each of our 5 probes has collected at least 10 results each:

Probe Results

Rotterdam 5 5 6 6 5 4 4 100

Athens 12 14 13 11 12 15 17 12

Vancouver 13 13 13 13 14 13 15 12

São Paulo 32 33 34 35 36 37 38 39

Brisbane 312 333 380 400 331 301 310 312

Based on these results, we can calculate a median value:

Probe Median

Rotterdam 5

Athens 15

Vancouver 14

São Paulo 37

Brisbane 310


70Status Checks

The lookback value mentioned above determines the total number of pastmeasurement results we take into account to generate these median values. Values canrange from 1 to 10 and the default is 1.

Once we have a median value, the next part of the equation, your specified median_rtt_threshold comes into play. We compare our calculated median value to thecurrent value, and if the difference exceeds your threshold value, we post an alert.

To continue with our example, say that you've decided that you want to be alerted if anyprobe exceeds its median RTT by 10. Your query would look like this:


71Status Checks

# RequestGET https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=10&median_rtt_threshold=10

# Response..."234": { "alert": true, "alert_reasons": [ "latency" ], "all": [ 43.103, 43.363, 43.517, 45.254, 45.303, 45.714, 45.72, 46.045, 46.907, 46.92, 47.338, 48.843, 49.831, 50.598, 50.834, 55.644, 65.612, 73.656, 78.739, 81.618, 101.793, 105.107, 111.606, 138.973, 144.736, 154.633, 159.825, 199.248, 206.075, 314.524 ], "last": 111.606, "last_packet_loss": 0.0, "median": 55.644, "source": "Country: GR"},...


72Status Checks

You'll note that not only has an alert been triggered due to the disparity between median and last , but also that alert_reasons now contains latency instead of what you mayhave seen until now: loss . It's possible that in some cases, you could have a sufficientnumber of dropped packets to trigger an alert and a sufficient amount of latency, so thisproperty will help you figure out which is which.

You can vary the lookback value if you like, and this will adjust the number of samplesused to establish a median.

A note about the lookback value

Median calculations are based only on the non-null values available. This meansthat if lookback=10 and of those 10 results only 2 of them are non-null, only thosetwo results will be used to calculate the median.

Supported median_rtt_thresholds include both percentages and integers, positive andnegative. Some examples:

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=10&median_rtt_threshold=10https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=10&median_rtt_threshold=10%https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=10&median_rtt_threshold=-10https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=10&median_rtt_threshold=-10%

Note however that you should be careful with using integers, as there's always likely tobe a strong variance for probes located a long distance for their target.

Sanity Filter

In the case of very low median values, a sanity check is applied to prevent alertsfrom being issued for no reason. An example of this might be a probe with amedian RTT of 2.3 and a latest RTT of 4.6. That's a 200% increase, but not oneworthy of note, so our sanity filter will not consider this worthy of an alert.

At present, the sanity filter ignores any delta of ±5ms.

Combinations

So now that we've covered all of the different options, you can try combining them to seewhat kind of results you might get.


73Status Checks

This will will only alert on probes that exceed a packet loss of 50%, and will only post aglobal alert if more than 3 probes are alerting:

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?permitted_total_alerts=3&max_packet_loss=50

Same thing, but this will always show the RTT values:

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?show_all=1&permitted_total_alerts=3&max_packet_loss=50

Looking back over the last 7 results, show alerts for probes exceeding the median RTTby 30%

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=7&median_rtt_threshold=30&show_all=1&permitted_total_alerts=3&max_packet_loss=50

The same thing, and again we include all RTT values:

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=7&median_rtt_threshold=30%&show_all=1

The same thing again, but this time only sound a global alert if more than 5 probes arealerting:

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=7&median_rtt_threshold=30%&show_all=1&permitted_total_alerts=5

And finally, a great big one that will:

Establish a median for each probe based on the past 10 resultsAlert any probe whose latest RTT exceeds that of the median by 20%Show all RTTs, regardless of alert statusWill only show a global alert if more than 7 probes are alertingWill mark a probe as alerting if the packet loss on that probe exceeds 50%

https://atlas.ripe.net/api/v2/measurements/123456789/status-check/?lookback=10&median_rtt_threshold=20%&show_all=1&permitted_total_alerts=7&max_packet_loss=50


74Status Checks


75Status Checks

Monitoring Integration ExampleIcinga

This example simply parses the output for global_alert":false and makes use of thebuilt in check_http plugin.

define service { use generic-service host_name myhostname service_description Test_Atlas check_command check_http!-I atlas.ripe.net -r 'global_alert":false' --ssl=1 -u /api/v2/measurements/1040425/status-check/?permitted_total_alerts=1}


76Status Checks

Frequently Asked QuestionsWhat if I want to measure the activity of just one probe ina measurement?

The idea behind this method is to measure the condition of the target and its relation tothe probes, rather than a means to check the status of an individual probe.

If your concern is the performance of a particular probe (or set of probes), you mustmeasure that probe's connectivity against a known target. For these purposes, werecommend the use of a RIPE Atlas Anchor or some other target with a predictablestatus.

Do you implement any Caching?

In an effort to reduce the load on our servers, the results of status-check requests arecached for 1 minute. So, if you tailor your monitoring software to query this service inintervals < 1 minute, you'll be wasting bandwidth and resources on both sides.

Where can I find more examples for using Status Checksin monitoring systems?

A Github repo is being maintained by the community for examples in different monitoringsystems. Feel free to add your own.


77Status Checks

My measurementsYou can get a list of your own measurements if you include a key - with sufficientpermissions - that was created by you:

https://atlas.ripe.net/api/v2/measurements/my/?key=<YOURKEY>

The key has to to have either "create measurement" or "download results ofmeasurements" permissions. The listing will return not only the measurements createdwith that key, but ALL measurements belonging to the user who created the given key.

The resource https://atlas.ripe.net/api/v2/measurements/my/ also gives a listing ofyour measurements if you are logged in and will replace the ?mine=true queryparameter.


78My measurements

Query Parameters for ProbesYou can filter on most of the fields of the probe, directly, in the same vein as you wouldwith measurements. The list of all filter query parameters is here.

A few interesting filters are those that do location based filtering.

There is a latitude and a longitude filter that can also be combined with a __gte and __lte suffix. Thus you could form a bounding box in which you want to look forprobes:

https://atlas.ripe.net/api/v2/probes/?latitude__gte=40.0&latitude__lte=46.0&longitude__gte=70&longitude__lte=75

Another interesting geo-location filter is the combined use of a latitude, longitude and aradius. This filter is bundled one single radius= query parameter and searches probeswithin the defined circle. It has the following syntax:

https://atlas.ripe.net/api/v2/probes/?radius=51.5,0.12:10


79Query Parameters

Probe TagsRIPE Atlas probes may be tagged to indicate properties, capabilities, network topologyor any other information. There are two kinds of tags: user tags and system tags. Eachtag consists of a human-readable name, possibly including spaces, and a hyphenated"slug" that is used when interacting with the API.

You can search for probes with a particular combination of tags using the API - see theAPI documentation for details.

User TagsUser tags may be applied and removed by the probe owner by going to the probes list,selecting the desired probe and choosing "Edit". It is then possible to select from a list ofcommonly used tags, or create a custom tag. We periodically review custom tags so wecan merge similar ones and suggest them to other users.

System TagsThe RIPE Atlas system periodically applies special tags to probes. These tags can berecognised through the following characteristics:

Their human-readable name begins with "system:", or they appear in the "SystemTags" section on the probe page.Their "slug", used for querying the API, begins with "system-".

It is impossible for a RIPE Atlas user, including probe owners, to apply or remove asystem tag, or to create a tag that begins with a "system" prefix.

Methodology


80Tags

Probes are re-assessed every four hours for each tag by inspecting certain baselineRIPE Atlas measurement results. The lookback period for this inspection is also fourhours. If, for some reason, there are no results from a probe, such as when it has beenoffline for a while, then no tags will be added or removed.

Tags

Several categories of system tags are assigned to probes:

Basic Connectivity

These tags indicate whether RIPE Atlas believes a probe works or does not work overIPv4 and IPv6. A probe is considered to work over a particular IP version if it has at leastone successful ping result for any one of a selection of baseline targets. It is consideredto not work if it only returns failures.

If there are no results for one IP version, but there are results for the other version, thenany existing tag for the first version will be removed.

The selection of measurement targets is diverse in that it includes anycast and unicastservers belonging to different organisations and having different purposes.

system: IPv4 Works (system-ipv4-works)system: IPv4 Doesn't Work (system-ipv4-doesnt-work)system: IPv6 Works (system-ipv6-works)system: IPv6 Doesn't Work (system-ipv6-doesnt-work)

Protocol Capability

system: IPv4 Capable (system-ipv4-capable)system: IPv6 Capable (system-ipv6-capable)system: IPv4 RFC1918 address is configured (system-ipv4-rfc1918)system: IPv6 ULA is configured (system-ipv6-ula)

DNS Resolution


81Tags

These tags indicate whether a probe can resolve simple hostname records to theexpected IP address. A probe is considered to be able to resolve if there is at least onecorrect response from each of its local resolvers. It is considered unable to reliablyresolve if at least one of its local resolvers only returns failures. It is considered toresolve incorrectly if there is at least one incorrect result for each queried A or AAAArecord.

If a probe submits any results from any of its local resolvers in which the name in thequestion section of the DNS request does not match the name in the answer section ofthe DNS reply in terms of upper/lower case (a 0x20 bit check), then it is tagged asmangling the cases and no other DNS tags will be applied.

system: Can Resolve A (system-can-resolve-a)system: Resolves A Incorrectly (system-resolves-a-incorrectly)system: Cannot Resolve A (system-cannot-resolve-a)system: Can Resolve AAAA (system-can-resolve-aaaa)system: Resolves AAAA Incorrectly (system-resolves-aaaa-incorrectly)system: Cannot Resolve AAAA (system-cannot-resolve-aaaa)system: Resolver Mangles Case (system-resolver-mangles-case)

The A and AAAA records used for these tests are delegated to various unrelated DNSservers.

Probe Metadata

These tags are not based on measurement results. Instead, they reflect a probe'sintrinsic properties, such as its version (1, 2 or 3), and whether or not it is also a RIPEAtlas anchor.

system: V1 (system-v1)system: V2 (system-v2)system: V3 (system-v3)system: Anchor (system-anchor)


82Tags

Participation RequestsParticipation requests allow you to add or remove probes from a measurement that wasalready created. Its structure is similar to the probes object that is used in the creationrequest for a measurement. The main difference is that a participation-request objectholds an action field, that can have a value remove or add .

The probes object that was included in the creation of the measurement is also presentin the Measurement API response as a participation-request object with an action value of add ..

Getting Information about Participation Change Requests

You can include the participation-requests array in a Measurement API request:

https://atlas.ripe.net/api/v2/measurements/2000000?optional_fields=participation_requests

As you can see the particiaption-request has its own ID. You can also use that toquery the Participation-requests API directly:

https://atlas.ripe.net/api/v2/participation-requests/2340391?optional_fields=participation_requests

Creating a Participation Change Request

Here's a simple example that adds one probe from the Netherlands to a runningmeasurement:


83Participation Requests

If you added a key with the right permissions you will get the following response:

{"requests": [35878]}

Please note that the request is actually made by making a POST request to the URI ofthe measurement involved and then appending /participation-requests/ .

On success it returns the data structure with the list of IDs of change requests created.

It is possible to create multiple changes in a single request

{ "probes" : [ { "action": "add", "requested": 1, "type": "country", "value": "CA" }, { "action": "remove", "requested": 1, "type": "probes", "value": "4,103" }, .... ]}

Please note that removal requests are only possible with type="probes". The field"value" has to be assigned a list of probes that are supposed to be removed.


84Participation Requests

Measurement ResultsA measurement result is the series of results of a single measurement performed by onesingle probe. This will usually consist of just one result only if the measurement was aone-off measurement.

If a measurement was performed by a probe, the measurement object will hold a URL inthe field called result that points to its measurement result. The URL will always looklike this:

https://atlas.ripe.net/api/v2/measurements/2000000/results/?start=1431459634

The response can be very large. For example, a probe that has been running ameasurement for a year with an interval of one minute will return 525,600 responses in asingle measurement results request.

RIPE Atlas will stream the actual response, so that you don't have to wait for theresponse to be completely assembled in the back-end. Instead, the back-end will startsending the response as soon as a single result is present.

The response and query parameters differ quite a lot from other APIs. The semanticsand syntax of the response is documented in great detail here.

The measurement results API only takes two query parameters. They allow you tospecify the time window for the returned measurement results. The lower limit is set withthe start query parameter and the upper limit is set with the stop parameter. Bothparameters require a UNIX timestamp as their input.

None of the generic query parameters work on the measurement result API.


85Measurement Results

Tips and Tricks


86Tips and Tricks

Overcoming the 20,000 Objects LimitAs mentioned earlier, there is currently no way to get more than 20,000 objects backfrom a single API request, not even in a paginated fashion. In other words, the total_count field in a request will never exceed 20,000, even though there might betwo million objects in the RIPE Atlas data.

This limit exists for performance reasons. To overcome this limit, you can move thecursor in the request yourself, with the aid of the id__gt query parameter.

Let's say you want to retrieve the first 80,000 measurements in RIPE Atlas, starting fromthe measurement with ID 2,000,000. You'd start out with a regular request, but with aquery parameter ?offset=19900 . This will get you the last page of the first 20,000measurements in the RIPE Atlas database:

https://atlas.ripe.net/api/v1/measurement/?offset=19900&id__gte=2000000

The total_count field is 20,000. Now, scroll all the way down and look up the msm_id of the last measurement in the list.

You can now use this msm_id in a new request with the query parameter id__gt=<YOURLAST ID> to retrieve the next 20,000 measurements:

https://atlas.ripe.net/api/v1/measurement/?id__gt=2020399


87Overcoming the 20,000 objects limit

More Documentation and ReferencesThe full reference documentation for most of the APIs is available here.A detailed description of Measurement Results can be found here.You can browse all the GET and OPTIONS requests to the RIPE Atlas APIs directlyfrom your browse. You can start here.All of the documentation for RIPE Atlas is located here.Our open source libraries for using RIPE Atlas have documentation onreadthedocs.org, they are called Sagan and Cousteau. Their repositories arelocated respectively here and here.


88More Documentation and References

Glossary

AttributeAn attribute is a property of a measurement as passed on to the probes. An attribute cantypically be set by the user when creating a measurement.

3.1.6.2. Complex Example 3.1.3.2.2. Type specific Attributes

Built-in measurementMeasurements that the RIPE Atlas system schedules and runs on each probe bydefault. These measurements are read-only for everybody and cannot be changed.

FieldA field in the context of the API is any property of any JSON object returned by the API.

3.1.2. Measurement Query Parameters 2.8. Result Streams API3.1.1. Type of Information 3.1.3. Create Measurements3.1.3.2. The definitions array 3.1.3.4. Fields for all Definitions3.1.3.3.1. In Detail 3.4. Measurement Results4.1. Overcoming the 20,000 objects limit 2.5.1. fields and optional_fields2.6.1. Anonymous User 2.9. Error Messages 2.5.2. page and page_size2.5.5. more query parameters 2.4. Object Detail Resources2.3. Object List Resources 3.3. Participation Requests

MeasurementA `Measurement` in the context of the RIPE Atlas APIs is an object holding informationabout one measurement (called a "one-off" measurement) or a series of measurementsperformed by one or multiple probes on the RIPE Atlas network.


89Glossary

3.1.6.1. Simple Example 3.1. Measurements 3.1.5. Latest measurements3.1.7. My measurements 3.1.2. Measurement Query Parameters2.8. Result Streams API 3.1.6.2. Complex Example3.1.6.4. Frequently Asked Questions 3.1.6. Status Checks3.1.4. Stop Measurements 3.1.1. Type of Information 3.1.3.1. Simple Example3.1.3. Create Measurements 3.1.3.2.1. Base Attributes3.1.3.2. The definitions array 3.1.3.5. A Full Example3.1.3.4. Fields for all Definitions 3.1.3.3.1. In Detail 3.1.3.3. The probes array3.1.3.2.2. Type specific Attributes 3.4. Measurement Results4.1. Overcoming the 20,000 objects limit 2.6.2. API Keys 2.9. Error Messages2.5.2. page and page_size 2.5.5. more query parameters 2.7. Authorization3.3. Participation Requests 3.2.2. Tags

Measurement definitionThe collection of attributes for a requested measurement as created by a user andpassed on to RIPE Atlas. A measurement definition is completed with default values forany attributes that the user did not otherwise specify values for.

3.1.3. Create Measurements 3.1.3.2.1. Base Attributes3.1.3.2. The definitions array

Measurement resultThe series of responses of an single measurement performed by a single probe. Thiswill equate to one response if the measurement was a one-off measurement.

3.1.5. Latest measurements 3.4. Measurement Results

Measurement resultsThe collection of all individual measurement results from all probes involved in onemeasurement.

3.1.5. Latest measurements 2.8. Result Streams API


90Glossary

3.1.6.2. Complex Example 3.4. Measurement Results5. More Documentation and References 1. Overview 3.2.2. Tags

Measurement specificationThe collection of attributes used by a probe to perform a measurement and return ameasurement result. The measurement specification can be read from the measurementAPI.

3.1. Measurements 3.1.1. Type of Information 3.1.3.2. The definitions array

ObjectIn the context of the API, an object is a unit described as a JSON object. The object hasfields that, together, describe the properties of the object. An example of an object is a`Measurement`.

3.1. Measurements 3.1.1. Type of Information 3.1.3. Create Measurements3.1.3.3.1. In Detail 3.4. Measurement Results 3. Object Documentation2.5.1. fields and optional_fields 2.1. A Basic Request 2.6.1. Anonymous User2.5. Generic Query Parameters 2.5.3. include 2.5.2. page and page_size2.4. Object Detail Resources 2.3. Object List Resources2.2. Two Types or Resources 3.3. Participation Requests

One-off measurementA single measurement performed one time only.

3.4. Measurement Results

Participation requestObject and resource that allows the owner of a measurement to add or remove probes,by specifying a selection.


91Glossary

ResourceAn end point on the web API that holds either a list of objects, or a detailed view of oneobject.

3.1.7. My measurements 3.1.1. Type of Information 2.1. A Basic Request2.6.1. Anonymous User 2.4. Object Detail Resources2.3. Object List Resources 2.2. Two Types or Resources

REST interfacesApplication interface that can be queried over HTTPS using a URL.

0. Introduction

UDMUser-defined measurement.

User-defined measurementCustomised measurements that users create themselves, as opposed to built-inmeasurements.


92Glossary

RIPE Atlas API v2 manual · PDF fileRIPE Atlas APIs Manual This is the manual for the RIPE...

Documents

Transcript of RIPE Atlas API v2 manual · PDF fileRIPE Atlas APIs Manual This is the manual for the RIPE...