PartyCrasher REST API 0.2.0¶

Overview¶

Modeled after the GitHub API, the returned JSON contains full-qualified URLs to resources (based on the User-Agent facing host).

All paths may be prefixed with /:project/

Most paths are also available without the /:project/ prefix in case the project is unknown or unspecified.

There are three entities:

Buckets

Reports

Projects

Conventions¶

Resource Links¶

Resources may be projects, buckets, reports, and other such entities.

A resource contains its hyperlink reference (i.e., URL), and (sometimes) its link relation.

{
    "resource": {
        "href": "http://domain.tld/path/to/resource"
    }
}

Endpoints at a glance¶

partycrasher
├── <project name>
│   ├── buckets
│   |   └── <threshold>
│   |       └── <bucket id>
│   ├── config
│   └── reports
│       └── dry_run
├── buckets
|   └── <threshold>
|       └── <bucket id>
├── config
└── reports
    └── dry_run

Upload a new report¶

POST /:project/reports HTTP/1.1

or

POST /reports HTTP/1.1

Uploads a new report. The report should be sent as a JSON Object with at least a unique database_id property. If uploaded to /:project/reports, the project property will automatically be set; otherwise, the project property is also mandatory.

The report may also have a date property, which will be used to group crashes by date. If not specified, this is set as the insertion date (which may not always be what you want).

The response contains the bucket assignments, as well as the canonical URL to access the report.

The report may also have a force_bucket property which will force the report to be bucketed in a particular bucket. This is only useful for testing purposes.

HTTP/1.1 201 Created
Location: https://your.host/<project>/report/<report-id>/

{
    "database_id": "<report-id>",
    "project": "<project>",
    "href": "https://domain.tld/<project>/reports/<report-id>",
    "buckets": {
        "4.0": {
            "bucket_id": "<bucket-id @ 4.0>",
            "href": "https://domain.tld/<project>/buckets/4.0/<bucket-id @ 4.0>"
        }
    }
}

Errors¶

When an identical (not just duplicate) report is posted:

HTTP/1.1 303 See Other
Location: https://domain.tld/<project>/report/<report-id>/

When a report is posted to a :project/ URL, but the report declares it belongs to a different project:

HTTP/1.1 400 Bad Request

Upload multiple new reports¶

POST /:project/reports HTTP/1.1

or

POST /reports HTTP/1.1

Send multiple reports (formatted as in Upload a new report) bundled up in a JSON Array (list). The response is a JSON Array of report results. Similar errors and statuses apply.

HTTP/1.1 201 Created

[
    {
        "database_id": "<report-id 1>",
        "project": "<project>",
        "href": "https://domain.tld/<project>/reports/<report-id 1>",
        "buckets": {
            "4.0": {
                "bucket_id": "<bucket-id @ 4.0>",
                "href": "https://domain.tld/<project>/buckets/4.0/<bucket-id @ 4.0>"
            }
        }
    },
    {
        "database_id": "<report-id 2>",
        "project": "<project>",
        "href": "https://domain.tld/<project>/reports/<report-id 2>",
        "buckets": {
            "4.0": {
                "bucket_id": "<bucket-id @ 4.0>",
                "href": "https://domain.tld/<project>/buckets/4.0/<bucket-id @ 4.0>"
            }
        }
    }
]

Errors¶

When an identical (not just duplicate) report is posted:

HTTP/1.1 303 See Other
Location: https://domain.tld/<project>/report/<report-id>/

When a report is posted to a :project/ URL, but the report declares it belongs to a different project:

HTTP/1.1 400 Bad Request

Upload a report (dry-run)¶

POST /:project/reports/dry-run HTTP/1.1

or

POST /reports/dry-run HTTP/1.1

Answers the question: “What bucket would this report be assigned to?” This does NOT store or track the report! Use Upload a new report to commit reports to the database.

HTTP/1.1 200 OK

{
    "database_id": "<report-id>",
    "href": "https://domain.tld/<project>/reports/<report-id>"
    "buckets": {
        "4.0": {
            "bucket_id": "<bucket-id @ 4.0>",
            "href": "https://domain.tld/<project>/buckets/4.0/<bucket-id @ 4.0>"
        }
    }
}

Analyse a report and return the most significant bits¶

GET /:project/reports/:report_id/summary HTTP/1.1

Summarises a processed report from the database.

{
    "database_id": "<report-id>",
    "project": "<project>",
}

Compare two reports and return various things¶

GET /reports/:report_id/compare/:other_id HTTP/1.1

Comp

{
    "database_id": "<report-id>",
    TBD
}

Get an existing report¶

GET /:project/reports/:report_id HTTP/1.1

Fetches a processed report from the database. This includes all data originally posted, plus bucket assignments, and the URLs for every relevant resource (buckets and project).

Warning

Due to ElasticSearch’s Near Realtime nature, when you GET a report immediately after a POST or a DELETE may not result in what you’d expect! Usually, it takes a few seconds for any changes to fully propagate throughout the database.

HTTP/1.1 200 OK
Link: <https://domain.tld/<project>/buckets/<T=[default]>/<bucket-id>; rel="related"

{
    "database_id": "<report-id>",
    "project": "<project>",
    "buckets": {
        "3.5": {
            "id": "<bucket-id, T=3.5>",
            "url": "https://domain.tld/<project>/buckets/3.5/<bucket-id>"
        },
        "4.0": {
            "id": "<bucket-id, T=4.0>",
            "url": "https://domain.tld/<project>/buckets/4.0/<bucket-id>"
        },
        "4.5": {
            "id": "<bucket-id, T=3.5>",
            "url": "https://domain.tld/<project>/buckets/4.5/<bucket-id>"
        }
    },

    "threads": [
        {
            "stacktrace": ["..."]
        }
    ],
    "comment": "<some flattering and not-at-all insulting comment about your software>",
    "os": "<os>",
    "platform": "<x86/arm, etc.>"
}

Get the top buckets in the recent past¶

GET /:project/buckets/:threshold HTTP/1.1

or

GET /buckets/:threshold HTTP/1.1

Finds the top buckets for a given time-frame. If queried on a :project route, implicitly filters by project.

Query parameters¶

q: Only show buckets, with crashes matching this search query, in lucene search syntax. See https://lucene.apache.org/core/2_9_4/queryparsersyntax.html for details.
since: Required. Grab buckets since this date, represented as an ISO 8601 date/time value (i.e, YYYY-MM-DD), or a relative offset such as 5-hours-ago, 3-days-ago or 1-week-ago, etc.
until: Grab buckets with crashes up to but not after this date as represented as an ISO 8601 date/time value. Defaults to no limit.
from: Get page of results starting from this number.
size: Get this number of results, starting from from.

Example¶

GET /alan_parsons/buckets/4.0?since=2016-02-29 HTTP/1.1
Host: domain.tld

HTTP/1.0 200 OK
Content-Type: application/json

{
    "since": "2016-02-29T00:00:00",
    "threshold": "4.0",
    "top_buckets": [
        {
            "id": "c29a81a0-5a53-4ba0-8123-5e96685a5895",
            "href": "http://domain.tld/alan_parsons/buckets/4.0/c29a81a0-5a53-4ba0-8123-5e96685a5895",
            "total": 253,
            "first_seen": "2016-02-27T14:32:08Z"
        }
    ]
}

View reports in a bucket¶

GET /:project/buckets/:threshold/:bucket_id HTTP/1.1

Fetches the bucket in given project, for the given threshold. Returns with a list of top reports (a semi-arbitrary list), and the amount of reports ingested into this bucket.

Query parameters¶

from: Get page of crash reports starting from this number.
size: Get this number of crash reports, starting from from.

HTTP/1.1 200 OK

{
    "id": "<bucket-id>",
    "project": "<project>",
    "href": "http://domain.tld/<project>/buckets/<threshold>/<bucket-id>",
    "threshold": "4.0",
    "top_reports": ["..."],
    "total": 3279
}

Perform a free-text search¶

GET /:project/search?q=:search HTTP/1.1

Performs a free-text search on all crashes in a project.

Query parameters¶

q: What to search for, in lucene search syntax. See https://lucene.apache.org/core/2_9_4/queryparsersyntax.html for details.
since: Search crashes occuring after this date, represented as an ISO 8601 date/time value (i.e, YYYY-MM-DD), or a relative offset such as 5-hours-ago, 3-days-ago or 1-week-ago, etc.
until: Search crashes occuring before this date as represented as an ISO 8601 date/time value. Defaults to no limit.
from: Get page of results starting from this number.
size: Get this number of results, starting from from.
sort: Change how the results are sorted. Specifies a field name such as date.
order: Should be asc or desc. Default is desc. Determines whether the results should be sorted in ascending or descending order.

HTTP/1.1 200 OK

[
    {
        "database_id": "<report-id>",
        "href": "https://domain.tld/<project>/reports/<report-id>"
        "buckets": {
            "4.0": {
                "bucket_id": "<bucket-id @ 4.0>",
                "href": "https://domain.tld/<project>/buckets/4.0/<bucket-id @ 4.0>"
            }
        }
    },
    {
        "database_id": "<report-id>",
        "href": "https://domain.tld/<project>/reports/<report-id>"
        "buckets": {
            "4.0": {
                "bucket_id": "<bucket-id @ 4.0>",
                "href": "https://domain.tld/<project>/buckets/4.0/<bucket-id @ 4.0>"
            }
        }
    },
    ...
]

Delete every report in the database¶

DELETE /reports HTTP/1.1

Deletes every report in the database. Requires that partycrasher.elastic.allow_delete_all be set in the configuration.

Warning

Issuing this command deletes every report in the database. All of them.

HTTP/1.1 200 OK

View per-project configuration¶

GET /:project/config HTTP/1.1

HTTP/1.1 200 OK

{
    "default_threshold": 4.0
}