.. index:: middleware

Middleware API

API map

New-style, documented services

crashes/
extensions/
products/
- products/builds/
- products/versions/
report/
- report/list/
search/
- search/crashes/
- search/signatures/
util/
- util/versions_info/

Old-style, undocumented services

See source code in .../socorro/services/ for more details.

/adu/byday
/adu/byday/details
/bugs/by/signatures
/crash
/current/versions
/email
/emailcampaigns/campaign
/emailcampaigns/campaigns/page
/emailcampaigns/create
/emailcampaigns/subscription
/emailcampaigns/volume
/reports/hang
/schedule/priority/job
/topcrash/sig/trend/history
/topcrash/sig/trend/rank

Crashes Comments

Return a list of comments on crash reports, filtered by signatures and other fields.

API specifications

HTTP method	GET
URL schema	/crashes/comments/(parameters)
Full URL	/crashes/comments/signature/(signature)/products/(products)/from/(from_date)/to/(to_date)/versions/(versions)/os/(os_name)/branches/(branches)/reasons/(crash_reason)/build_ids/(build_ids)/build_from/(build_from)/build_to/(build_to)/report_process/(report_process)/report_type/(report_type)/plugin_in/(plugin_in)/plugin_search_mode/(plugin_search_mode)/plugin_terms/(plugin_terms)/
Example	http://socorro-api/bpapi/crashes/comments/signature/SocketSend/products/Firefox/versions/Firefox:4.0.1/from/2011-05-01/to/2011-05-05/os/Windows/

Mandatory parameters

Name	Type of value	Default value	Description
signature	String	None	Signature of crash reports to get.

Optional parameters

Name	Type of value	Default value	Description
products	String or list of strings	'Firefox'	The product we are interested in. (e.g. Firefox, Fennec, Thunderbird… )
from	Date	Now - 7 days	Search for crashes that happened after this date. Can use the following formats: 'yyyy-MM-dd', 'yyyy-MM-dd HH:ii:ss' or 'yyyy-MM-dd HH:ii:ss.S'.
to	Date	Now	Search for crashes that happened before this date. Can use the following formats: 'yyyy-MM-dd', 'yyyy-MM-dd HH:ii:ss' or 'yyyy-MM-dd HH:ii:ss.S'.
versions	String or list of strings	None	Restring to a specific version of the product. Several versions can be specified, separated by a + symbol.
os	String or list of strings	None	Restrict to an Operating System. (e.g. Windows, Mac, Linux… ) Several versions can be specified, separated by a + symbol.
branches	String or list of strings	None	Restrict to a branch of the product. Several branches can be specified, separated by a + symbol.
reasons	String or list of strings	None	Restricts search to crashes caused by this reason.
build_ids	Integer or list of integers	None	Restricts search to crashes that happened on a product with this build ID.
build_from	Integer or list of integers	None	Restricts search to crashes with a build id greater than this.
build_to	Integer or list of integers	None	Restricts search to crashes with a build id lower than this.
report_process	String	'any'	Can be 'any', 'browser' or 'plugin'.
report_type	String	'any'	Can be 'any', 'crash' or 'hang'.
plugin_in	String or list of strings	'name'	Search for a plugin in this field. 'report_process' has to be set to 'plugin'.
plugin_search_mode	String	'default'	How to search for this plugin. report_process has to be set to plugin. Can be either 'default', 'is_exactly', 'contains' or 'starts_with'.
plugin_terms	String or list of strings	None	Terms to search for. Several terms can be specified, separated by a + symbol. report_process has to be set to plugin.

Return value

In normal cases, return something like this:

{
    "hits": [
        {
            "date_processed": "2011-03-16 06:54:56.385843",
            "uuid": "06a0c9b5-0381-42ce-855a-ccaaa2120116",
            "user_comments": "My firefox is crashing in an awesome way",
            "email": "someone@something.org"
        },
        {
            "date_processed": "2011-03-16 06:54:56.385843",
            "uuid": "06a0c9b5-0381-42ce-855a-ccaaa2120116",
            "user_comments": "I <3 Firefox crashes!",
            "email": "someone@something.org"
        }
    ],
    "total": 2
}

If no signature is passed as a parameter, return null.

Crashes Paireduuid

Return paired uuid given a uuid and an optional hangid.

API specifications

HTTP method	GET
URL schema	/crashes/paireduuid/(optional_parameters)
Full URL	/crashes/paireduuid/uuid/(uuid)/hangid/(hangid)/
Example	http://socorro-api/bpapi/crashes/paireduuid/uuid/e8820616-1462-49b6-9784-e99a32120201/

Mandatory parameters

Name	Type of value	Description
uuid	String	Unique identifier of the crash report.

Optional parameters

Name	Type of value	Default value	Description
hangid	String	None	Hang ID of the crash report.

Return value

Return an object like the following:

{
    "hits": [
        {
            "uuid": "e8820616-1462-49b6-9784-e99a32120201"
        }
    ],
    "total": 1
}

Note that if a hangid is passed to the service, it will always return maximum one result. Remove that hangid to get all paired uuid.

Crashes Signatures

Return top crashers by signatures.

API specifications

HTTP method	GET
URL schema	/crashes/signatures/(optional_parameters)
Full URL	/crashes/signatures/product/(product)/version/(version)/to_from/(to_date)/ duration/(number_of_days)/crash_type/(crash_type)/limit/(number_of_results)/ os/(operating_system)/
Example	http://socorro-api/bpapi/crashes/signatures/product/Firefox/version/9.0a1/

Mandatory parameters

Name	Type of value	Description
product	String	Product for which to get top crashes by signatures.
version	String	Version of the product for which to get top crashes.

Optional parameters

Name	Type of value	Default value	Description
crash_type	String	all	Type of crashes to get, can be "browser", "plugin", "content" or "all".
end_date	Date	Now	Date before which to get top crashes.
duration	Int	One week	Number of hours during which to get crashes.
os	String	None	Limit crashes to only one OS.
limit	Int	100	Number of results to retrieve.

Return value

Return an object like the following:

{
    "totalPercentage": 0.9999999999999994,
    "end_date": "2011-12-08 00:00:00",
    "start_date": "2011-12-07 17:00:00",
    "crashes": [
        {
            "count": 3,
            "mac_count": 3,
            "changeInRank": 11,
            "currentRank": 0,
            "previousRank": 11,
            "percentOfTotal": 0.142857142857143,
            "win_count": 0,
            "changeInPercentOfTotal": 0.117857142857143,
            "linux_count": 0,
            "hang_count": 0,
            "signature": "objc_msgSend | __CFXNotificationPost",
            "previousPercentOfTotal": 0.025,
            "plugin_count": 0
        }
    ],
    "totalNumberOfCrashes": 1
}

Extensions

Return a list of extensions associated with a crash's UUID.

API specifications

HTTP method	GET
URL schema	/extensions/(optional_parameters)
Full URL	/extensions/uuid/(uuid)/date/(crash_date)/
Example	http://socorro-api/bpapi/extensions/uuid/xxxx-xxxx-xxxx/date/2012-02-29T01:23:45+00:00/

Mandatory parameters

Name	Type of value	Default value	Description
uuid	String	None	Unique Identifier of the specific crash to get extensions from.
date	Datetime	None	Exact datetime of the crash.

Optional parameters

None

Return value

Return a list of extensions:

{
    "total": 1,
    "hits": [
        {
            "report_id": 1234,
            "date_processed": "2012-02-29T01:23:45+00:00",
            "extension_key": 5678,
            "extension_id": "testpilot@labs.mozilla.com",
            "extension_version": "1.2"
        }
    ]
}

Products Builds

Return information about nightly builds of one or several products.

API specifications

HTTP method	GET
URL schema	/products/builds/(optional_parameters)
Full URL	/products/builds/product/(product)/version/(version)/date_from/(date_from)/
Example	http://socorro-api/bpapi/products/builds/product/Firefox/version/9.0a1/

Mandatory parameters

Name	Type of value	Default value	Description
product	String	None	Product for which to get nightly builds.

Optional parameters

Name	Type of value	Default value	Description
version	String	None	Version of the product for which to get nightly builds.
from_date	Date	Now - 7 days	Date from which to get nightly builds.

Return value

Return an array of objects:

[
    {
        "product": "string",
        "version": "string",
        "platform": "string",
        "buildid": "integer",
        "build_type": "string",
        "beta_number": "string",
        "repository": "string",
        "date": "string"
    },
    ...
]

Products Versions

Return information about product(s) and version(s) passed to the service.

API specifications

HTTP method	GET
URL schema	/products/(.*)
Full URL	/products/versions/(versions)/
Example	http://socorro-api/bpapi/products/versions/Firefox:9.0a1/

Mandatory parameters

Name	Type of value	Default value	Description
versions	String or list of strings	None	Several product:version strings can be specified, separated by a + symbol.

Return value

Return an object with an array of results labeled as hits and a total:

{
    "hits": [
        {
            "is_featured": boolean,
            "throttle": float,
            "end_date": "string",
            "start_date": "integer",
            "build_type": "string",
            "product": "string",
            "version": "string"
        }
        ...
    ],
    "total": 1
}

Search

Search for crashes according to a large number of parameters and return a list of crashes or a list of distinct signatures.

API specifications

HTTP method	GET
URL schema	/search/(data_type)/(optional_parameters)
Full URL	/search/(data_type)/for/(terms)/products/(products)/from/(from_date)/to/(to_date)/in/(fields)/versions/(versions)/os/(os_name)/branches/(branches)/search_mode/(search_mode)/reasons/(crash_reasons)/build_ids/(build_ids)/build_from/(build_from)/build_to/(build_to)/report_process/(report_process)/report_type/(report_type)/plugin_in/(plugin_in)/plugin_search_mode/(plugin_search_mode)/plugin_terms/(plugin_terms)/result_number/(number)/result_offset/(offset)/
Example	http://socorro-api/bpapi/search/crashes/for/libflash.so/in/signature/products/Firefox/versions/Firefox:4.0.1/from/2011-05-01/to/2011-05-05/os/Windows/

Mandatory parameters

Name	Type of value	Default value	Description
data_type	String	'signatures'	Type of data we are looking for. Can be 'crashes' or 'signatures'.

Optional parameters

Name	Type of value	Default value	Description
for	String or list of strings	None	Terms we are searching for. Each term must be URL encoded. Several terms can be specified, separated by a + symbol.
products	String or list of strings	'Firefox'	The product we are interested in. (e.g. Firefox, Fennec, Thunderbird… )
from	Date	Now - 7 days	Search for crashes that happened after this date. Can use the following formats: 'yyyy-MM-dd', 'yyyy-MM-dd HH:ii:ss' or 'yyyy-MM-dd HH:ii:ss.S'.
to	Date	Now	Search for crashes that happened before this date. Can use the following formats: 'yyyy-MM-dd', 'yyyy-MM-dd HH:ii:ss' or 'yyyy-MM-dd HH:ii:ss.S'.
in	String or list of strings	All	Fields we are searching in. Several fields can be specified, separated by a + symbol. This is NOT implemented for PostgreSQL.
versions	String or list of strings	None	Restring to a specific version of the product. Several versions can be specified, separated by a + symbol.
os	String or list of strings	None	Restrict to an Operating System. (e.g. Windows, Mac, Linux… ) Several versions can be specified, separated by a + symbol.
branches	String or list of strings	None	Restrict to a branch of the product. Several branches can be specified, separated by a + symbol.
search_mode	String	'default'	Set how to search. Can be either 'default', 'is_exactly', 'contains' or 'starts_with'.
reasons	String or list of strings	None	Restricts search to crashes caused by this reason.
build_ids	Integer or list of integers	None	Restricts search to crashes that happened on a product with this build ID.
build_from	Integer or list of integers	None	Restricts search to crashes with a build id greater than this.
build_to	Integer or list of integers	None	Restricts search to crashes with a build id lower than this.
report_process	String	'any'	Can be 'any', 'browser' or 'plugin'.
report_type	String	'any'	Can be 'any', 'crash' or 'hang'.
plugin_in	String or list of strings	'name'	Search for a plugin in this field. 'report_process' has to be set to 'plugin'.
plugin_search_mode	String	'default'	How to search for this plugin. report_process has to be set to plugin. Can be either 'default', 'is_exactly', 'contains' or 'starts_with'.
plugin_terms	String or list of strings	None	Terms to search for. Several terms can be specified, separated by a + symbol. report_process has to be set to plugin.
result_number	Integer	100	Number of results to return.
result_offset	Integer	0	Offset of the first result to return.

Return value

If data_type is crashes, return value looks like:

{
    "hits": [
        {
            "count": 1,
            "signature": "arena_dalloc_small | arena_dalloc | free | CloseDir",
        },
        {
            "count": 1,
            "signature": "XPCWrappedNativeScope::TraceJS(JSTracer*, XPCJSRuntime*)",
            "is_solaris": 0,
            "is_linux": 0,
            "numplugin": 0,
            "is_windows": 0,
            "is_mac": 0,
            "numhang": 0
        }
    ],
    "total": 2
}

If data_type is signatures, return value looks like:

{
    "hits": [
        {
            "client_crash_date": "2011-03-16 13:55:10.0",
            "dump": "...",
            "signature": "arena_dalloc_small | arena_dalloc | free | CloseDir",
            "process_type": null,
            "id": 231224257,
            "hangid": null,
            "version": "4.0b13pre",
            "build": "20110314162350",
            "product": "Firefox",
            "os_name": "Mac OS X",
            "date_processed": "2011-03-16 06:54:56.385843",
            "reason": "EXC_BAD_ACCESS / KERN_INVALID_ADDRESS",
            "address": "0x1d3aff03",
            "...": "..."
        }
    ],
    "total": 1
}

If an error occured, the API will return something like this:

Well, for the moment it doesn't return anything but an Internal Error
HTTP header... We will improve that soon! :)

List Report

Return a list of crash reports with a specified signature and filtered by a wide range of options.

API specifications

HTTP method	GET
URL schema	/report/list/(parameters)
Full URL	/report/list/signature/(signature)/products/(products)/from/(from_date)/to/(to_date)/versions/(versions)/os/(os_name)/branches/(branches)/reasons/(crash_reason)/build_ids/(build_ids)/build_from/(build_from)/build_to/(build_to)/report_process/(report_process)/report_type/(report_type)/plugin_in/(plugin_in)/plugin_search_mode/(plugin_search_mode)/plugin_terms/(plugin_terms)/
Example	http://socorro-api/bpapi/report/list/signature/SocketSend/products/Firefox/versions/Firefox:4.0.1/from/2011-05-01/to/2011-05-05/os/Windows/

Mandatory parameters

Name	Type of value	Default value	Description
signature	String	None	Signature of crash reports to get.

Optional parameters

Name	Type of value	Default value	Description
products	String or list of strings	'Firefox'	The product we are interested in. (e.g. Firefox, Fennec, Thunderbird… )
from	Date	Now - 7 days	Search for crashes that happened after this date. Can use the following formats: 'yyyy-MM-dd', 'yyyy-MM-dd HH:ii:ss' or 'yyyy-MM-dd HH:ii:ss.S'.
to	Date	Now	Search for crashes that happened before this date. Can use the following formats: 'yyyy-MM-dd', 'yyyy-MM-dd HH:ii:ss' or 'yyyy-MM-dd HH:ii:ss.S'.
versions	String or list of strings	None	Restring to a specific version of the product. Several versions can be specified, separated by a + symbol.
os	String or list of strings	None	Restrict to an Operating System. (e.g. Windows, Mac, Linux… ) Several versions can be specified, separated by a + symbol.
branches	String or list of strings	None	Restrict to a branch of the product. Several branches can be specified, separated by a + symbol.
reasons	String or list of strings	None	Restricts search to crashes caused by this reason.
build_ids	Integer or list of integers	None	Restricts search to crashes that happened on a product with this build ID.
build_from	Integer or list of integers	None	Restricts search to crashes with a build id greater than this.
build_to	Integer or list of integers	None	Restricts search to crashes with a build id lower than this.
report_process	String	'any'	Can be 'any', 'browser' or 'plugin'.
report_type	String	'any'	Can be 'any', 'crash' or 'hang'.
plugin_in	String or list of strings	'name'	Search for a plugin in this field. 'report_process' has to be set to 'plugin'.
plugin_search_mode	String	'default'	How to search for this plugin. report_process has to be set to plugin. Can be either 'default', 'is_exactly', 'contains' or 'starts_with'.
plugin_terms	String or list of strings	None	Terms to search for. Several terms can be specified, separated by a + symbol. report_process has to be set to plugin.
result_number	Integer	100	Number of results to return.
result_offset	Integer	0	Offset of the first result to return.

Return value

In normal cases, return something like this:

{
    "hits": [
        {
            "client_crash_date": "2011-03-16 13:55:10.0",
            "dump": "...",
            "signature": "arena_dalloc_small | arena_dalloc | free | CloseDir",
            "process_type": null,
            "id": 231224257,
            "hangid": null,
            "version": "4.0b13pre",
            "build": "20110314162350",
            "product": "Firefox",
            "os_name": "Mac OS X",
            "date_processed": "2011-03-16 06:54:56.385843",
            "reason": "EXC_BAD_ACCESS / KERN_INVALID_ADDRESS",
            "address": "0x1d3aff03",
            "...": "..."
        },
        {
            "client_crash_date": "2011-03-16 11:35:37.0",
            "...": "..."
        }
    ],
    "total": 2
}

If signature is empty or nonexistent, raise a BadRequest error.

If another error occured, the API will return a 500 Internal Error HTTP header.

Versions Info

Return information about one or several couples product:version.

API specifications

HTTP method	GET
URL schema	/util/versions_info/(optional_parameters)
Full URL	/util/versions_info/versions/(versions)/
Example	http://socorro-api/bpapi/util/versions_info/versions/Firefox:9.0a1+Fennec:7.0/

Mandatory parameters

None.

Optional parameters

Name	Type of value	Default value	Description
versions	String or list of strings	None	Product:Versions couples for which information is asked.

Return value

If parameter versions is unvalid, return value is None. Otherwise it looks like this:

{
    "product_name:version_string": {
        "version_string": "string",
        "product_name": "string",
        "major_version": "string" or None,
        "release_channel": "string" or None,
        "build_id": [list, of, decimals] or None
    }
}

Forcing an implementation

For debuging reasons, you can add a parameter to force the API to use a specific implementation module. That module must be inside socorro.external and contain the needed service implementation.

Name	Type of value	Default value	Description
force_api_impl	String	None	Force the service to use a specific module.

For example, if you want to force search to be executed with ElasticSearch, you can add to the middleware call force_api_impl/elasticsearch/. If socorro.external.elasticsearch exists and contains a search module, it will get loaded and used.

Files

middleware.rst

Latest commit

History

middleware.rst

File metadata and controls

Middleware API

API map

New-style, documented services

Old-style, undocumented services

Crashes Comments

API specifications

Mandatory parameters

Optional parameters

Return value

Crashes Paireduuid

API specifications

Mandatory parameters

Optional parameters

Return value

Crashes Signatures

API specifications

Mandatory parameters

Optional parameters

Return value

Extensions

API specifications

Mandatory parameters

Optional parameters

Return value

Products Builds

API specifications

Mandatory parameters

Optional parameters

Return value

Products Versions

API specifications

Mandatory parameters

Return value

Search

API specifications

Mandatory parameters

Optional parameters

Return value

List Report

API specifications

Mandatory parameters

Optional parameters

Return value

Versions Info

API specifications

Mandatory parameters

Optional parameters

Return value

Forcing an implementation