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.

The HTTP API provides two basic operations:

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.