ffledgling/Using_Senbonzakura.mkd

## Using_Senbonzakura.mkd

      
    Raw
  

              Using_Senbonzakura.mkd
            
          
    Using Funsize

So you've heard about this amazing new update service and want to give it a whirl, eh?
Alright, you'll find the instructions and hopefully, the first draft of the current API here.
This service is currently hosted at http://funsize-env-testing.elasticbeanstalk.com/
I'll begin by describing the API Endpoints, and then go on to describe easy ways to access and use the service.
API Endpoints

Please note, this is API v0.1
This means that the API is still a prototype, is unstable, and can change frequently.
It is not the responsibility of the developers to be backwards compatible until the API has been
declared stable, please check back often in case you plan to use the API.
Trigger Partial Generation

<service url>/partial
# Example
http://funsize-env-testing.elasticbeanstalk.com/partial

This API Endpoint is used for triggering or kicking off the generation of a partial.
A partial is essentially defined by the two versions of Firefox it helps transition between; A
source and a Destination.
To trigger generation you need to send a POST request to the URL end points with the following
parameters:

mar_from : URL to the complete MAR for the source Firefox Version
mar_to: URL to the complete MAR for the destination Firefox Version
mar_from_hash: SHA512 Hash of the complete MAR for the source Firefox Version
mar_to_hash : SHA512 Hash of the complete MAR for the destination Firefox Version
channel_id : Channel-ID typically refers to the release channel you're in

Possible values are one of firefox-mozilla-{release,beta,aurora,central}
product_version : Product version typically refers to destination Firefox's version.

Once a correct request has been made, you will receive a JSON response with an HTTP 201 response
code. The response contains a URL path relative to the base URL. The client can then poll on this URL.
While the application is still generating the partial it will return an HTTP 202 response. Once
done, the application will return an HTTP 200 response with the Partial in the response body.
In case of failure in the process of generating the Partial, the service might abort the request and
in such a case the client is informed of the same with an HTTP 500 response.
In case the where the client request is malformed the service will respond with an HTTP 400 response
code.
Getting the Partial

/partial/<identifier>
# Example Partial Download URL for Firefox 27 to Firefox 29 (en-US, linux64) transition
http://funsize-env-testing.elasticbeanstalk.com/partial/68d6f1fbc8bcb91337b302d16f34694bd060a06846787a2de36193a68b878d058e90c2c377db0e50744291545cbb472277cbed260f4591435ff15aba58c7fbbd-a1e7f848bed4a5f195e646c71b057dc289f901fa695b81859cfd5f732d764de30cbf9f43011bc3ec47e1da61aad5731d57ff5c49948ab265484df2d441e1a090

You can use this endpoint to access the actual Partial MARs that have been generated by this
service. The identifier is any valid identifier returned by a POST request to the /partial/ end
point.
Currently the identifier is simply a concatenation of the SHA512 hashes of the complete MARs
(SrcHash-DstHash), but this is subject to change. Do not rely on this behaviour, instead post a
request for the partial you need and use the URL returned by that request. You can re-request the
generation of the partial as many times as you like, the service exhibits idempotent behvaiour in
such a case.
Using the Service

If you're writing a client that will be using this service, you can use the above API docs for
fairly accurate behaviour description.
If you're a human testing out the service, it is recommended you use curl to send the POST requests.
Various scripts exist to help you out. See:
https://github.com/ffledgling/Senbonzakura/blob/master/Docker/docker-curl-test.sh # Trigger a pre-defined partial
https://github.com/ffledgling/Senbonzakura/blob/master/Docker/docker_poll.sh # Poll on the above URL
https://github.com/ffledgling/Senbonzakura/blob/master/tests/utility_scripts/generate_load.py # To generate the required paramaters in the required order, best used with the following script
https://github.com/ffledgling/Senbonzakura/blob/master/tests/utility_scripts/test-load-docker.sh

A usable web interface is also on the cards, but it's low down in our deck.