HTTP API

Note: The HTTP API is quite limited at the moment as it only contains the functionality necessary for a single use case - a stand-alone server for one Linux distribution. As more use cases likely to be implemented in the future, it is planned to extend the API heavily.

Accepting uReport

1) Request

To upload uReport client must send a request to $BASEURL/reports/new/ simulating uploading file from standard webform. The following rules apply:

The request MUST use POST method.
In order to receive a machine parseable response the request MUST contain Accept header and must accept application/json MIME type (otherwise the response will be HTML).
The Content-Type header MUST be set to multipart/form-data.
The body MUST contain an element named file with MIME type application/json. The content of that element is the uReport.

Example:

POST /faf/reports/new/ HTTP/1.1
Host: retrace.fedoraproject.org
Accept: application/json
Connection: close
User-Agent: ABRT/2.2.0
Content-Length: 82679
Content-Type: multipart/form-data; boundary=------------------------158cd5d5f4ca87bc

------------------------158cd5d5f4ca87bc
Content-Disposition: form-data; name="file"; filename="*buffer*"
Content-Type: application/json

{   "ureport_version": 2
,   "reason": "Program /usr/bin/vlc was terminated by signal 11"
,   "reporter": {   "name": "satyr"
                ,   "version": "0.13"
                }
,   "os": {   "name": "fedora"
          ,   "version": "20"
          ,   "architecture": "x86_64"
          ,   "cpe": "cpe:/o:fedoraproject:fedora:20"
          }
,   "problem": {
                  ... snip ...
               }
,   "packages": {
                  ... snip ...
                }
}
------------------------158cd5d5f4ca87bc--

2) Response

If the Accept header in the request specified application/json, the response body will be a JSON object. Several response types are possible:

Error
The HTTP status code will be 4** and the JSON object will contain a single element named error, with the error message. Example:

{"error": "uReport may only be 4096 bytes long"}

(the number 4096 may not reflect reality)

uReport unknown
The HTTP status code will be 202 ACCEPTED and the JSON object will contain an element named result with value false. An element named bthash will also be present if the report is filed against a supported component. This hash may serve for further referencing the report - the reports are not saved at the moment of uploading but batch-processed every few minutes, therefore it receives its ID later. Examples:

{"result": false}

{"result": false, "bthash": "cc1db4771634957accde8abb589d9e16e0566a01"}

uRerport known
The HTTP status code will be 202 ACCEPTED and the JSON object will contain an element named result with value true. An element named bthash may also be present (see above). If the report is linked with some external reports, the response will also contain a message element with a textual summary of the external reports and a reported_to element containing a list of those reports in structured format (reporter, type, value). If the report matches a knowledgebase entry, the message element will also contain a likely reason and an element solutions will contain a list of solutions in structured format (cause, note, url). Examples:

{"result": true, "bthash": "cc1db4771634957accde8abb589d9e16e0566a01"}

{
  "result": true,
  "message": "Your problem seems to be caused by VLC Media Player\n\nVLC media player includes codecs protected by patetnts.\nFedora does not ship such pieces of software. You are welcome to use\nopen formats in combination with Totem, Rhytmbox or amaroK media players.\n\nYou can get more information at http://fedoraproject.org/wiki/Multimedia",
  "solutions": [
    {
      "cause": "VLC Media Player",
      "url": "http://fedoraproject.org/wiki/Multimedia",
      "note": "VLC media player includes codecs protected by patetnts.\nFedora does not ship such pieces of software. You are welcome to use\nopen formats in combination with Totem, Rhytmbox or amaroK media players."
    }
  ]
}

{
  "result": true,
  "bthash": "058896b486386a0060459830992f69a275e7f3fd",
  "message": "https://retrace.fedoraproject.org/faf/reports/199733/\nhttps://bugzilla.redhat.com/show_bug.cgi?id=947761",
  "reported_to": [
    {
      "type": "url",
      "value": "https://retrace.fedoraproject.org/faf/reports/199733/",
      "reporter": "ABRT Server"
    },
    {
      "type": "url",
      "value": "https://bugzilla.redhat.com/show_bug.cgi?id=947761",
      "reporter": "Bugzilla"
    }
  ]
}

Getting report/problem ID from hash

Having the hash of a report obtained e.g. when uploading a report against a valid component (see above), one may want to get to the actual report ID / problem ID. For this the client must send a GET request to $BASEURL/reports/bthash/$HASH/ or $BASEURL/problems/bthash/$HASH/.

If the hash matches a report/problem on the server, the HTTP response will contain 302 Found status code and Location header pointing to the URL of the report/problem. The ID is easily parseable from the URL.
If the hash does not match any report/problem, the HTTP response will contain 404 Not Found status code.

Report statistics

1) Request

The request MUST use GET method.
In order to receive a machine parseable response the request MUST contain Accept header and must accept application/json MIME type (otherwise the response will be HTML).

2) Resources

$BASEURL/stats/today/, $BASEURL/stats/yesterday/, $BASEURL/stats/last_week/, $BASEURL/stats/last_month/, $BASEURL/stats/last_year/, $BASEURL/stats/date/$YYYY/, $BASEURL/stats/date/$YYYY/$mm/, $BASEURL/stats/date/$YYYY/$mm/$dd/, $BASEURL/stats/daterange/$YYYY-mm-dd/$YYYY-mm-dd/

3) Response

If the Accept header in the request specified application/json, the response body will be a JSON object.

Example:

$ curl -H "Accept: application/json" http://localhost/faf/stats/date/2014/07/15/
{
  "total":224,
  "to":"2014-07-16",
  "since":"2014-07-15",
  "releases":[
    {
      "release":"Fedora 20",
      "comps":[["kernel",195,87],["virtuoso-opensource",12,5],["gvfs",4,1],["tracker",3,1],["firefox",2,0],["remmina",1,0],["firewalld",1,0],["openbabel",1,0],["unrtf",1,0],["gnome-software",1,0],["gnome-shell",1,0]],
      "sum":222,
      "percentage":99
    },
    {
      "release":"Fedora 19",
      "comps":[["kernel",2,100]],
      "sum":2,
      "percentage":0}
  ]
}

Every component in the comps attribute is in the form [name, count, percentage].

Summary statistics

1) Request

The request MUST use GET method.
In order to receive a machine parseable response the request MUST contain Accept header and must accept application/json MIME type (otherwise the response will be HTML).

2) Resource

$BASEURL/summary/$RELEASES/$COMPONENTS/$DURATION/

$RELEASES may be * to select all OS releases, or specify a comma separated list of release name slugs, e.g. fedora-20,fedora-19
$COMPONENTS may be * to select all components, or specify a comma separated list of component names
$DURATION may be * to select all-time summary, d to select 14 days summary, w to select 8 weeks summary or m to select 12 months summary

3) Response

If the Accept header in the request specified application/json, the response body will be a JSON object.

Example:

$ curl -H "Accept: application/json" http://localhost/faf/summary/*/*/d/
[
  {
    "name": "All Fedora Releases",
    "timeseries": [
      {
        "date": "2014-07-11",
        "count": 477
      },
      {
        "date": "2014-07-12",
        "count": 381
      },
...
      {
        "date": "2014-07-25",
        "count": 0
      }
    ]
  },
  {
    "name": "Fedora 20",
    "timeseries": [
      {
        "date": "2014-07-11",
        "count": 388
      },
...
      {
        "date": "2014-07-25",
        "count": 0
      }
    ]
  }
]

Hot and long-term problems

1) Request

The request MUST use GET method.
In order to receive a machine parseable response the request MUST contain Accept header and must accept application/json MIME type (otherwise the response will be HTML).

2) Resource

$BASEURL/problems/hot/, $BASEURL/problems/longterm/

3) Response

If the Accept header in the request specified application/json, the response body will be a JSON object.

Example:

$ curl -H "Accept: application/json" http://localhost/faf/problems/hot/
[
  {
    "count": 11,
    "crash_function": "unknown function",
    "id": 890,
    "components": [
      "Thunar"
    ],
    "bugs": [
      "https://bugzilla.redhat.com/show_bug.cgi?id=123456789",
      "https://bugzilla.redhat.com/show_bug.cgi?id=123456790"
    ]
  },
  {
    "count": 1,
    "crash_function": "unknown function",
    "id": 1789,
    "components": [
      "Thunar"
    ],
    "bugs": [
      
    ]
  },
...
]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HTTP API

Accepting uReport

Getting report/problem ID from hash

Report statistics

Summary statistics

Hot and long-term problems

Clone this wiki locally