REST API

REST API

/api/birthmarks

GET available birthmark types

Returns an array of the available birthmark types.

Status code

• 200 OK
  • Always success.

Response Example

{ 
    types: [ "smc", "uc", "fuc", "kgram", "wsp" ]
}

/api/birthmarks/{types}

GET Description of the specified birthmark type.

Returns the description of the specified birthmark type.

Status code

• 200 OK
  • Given type was available.
• 404 Not Found
  • Given type was not supported (given type was not included in the response from /api/birthmarks).

Response Example

The response of /api/birthmarks/kgram is as follows.

{
     type: "kgram",
     description: "",
     parameters: [
         name: "k",
         required: true,
         description: ""
     ]
}

The parameters should give as query param.

POST Perform extraction

Request to extract the specified type of birthmarks from given jar/war/class files. The source of birthmarks are given by form data (application/x-www-form-urlencoded) or urls formatted by the following json form.

Status code

• 202 Accepted
  • The request was allowed, and pochi performs the birthmark extraction.
• 404 Not Found
  • Given type was not supported (given type was not included in the response from /api/birthmarks).
• 400 Bad Request
  • Required values are not specified.
  • The given files are invalid.
  • The url in given urls are not available.

Example of request body

{
    urls: [ "url1", "url2", ... ]
}

If the given url requires the authorization, the current version of pochi did not support.

Response Example

The request is allowed and success, the status code is 202 (Accepted), and respond json. The response contains the result url, key, status and expired date. Because, usually the birthmark extraction needs much time.

{
    result_url: "http://hostname/pochi/api/results/{id}?key={key}",
    status: working, // preparing, working, or done
    expire: "2018-10-20T24:00:00.000Z"
}

/api/similarities

GET Available birthmark type and corresponding comparison algorithms.

Response the available type and corresponding comparing algorithms.

Status code

• 200 OK
  • Always success.

Response Example

{
    algorithms: [
        { type: "smc", algorithms: [ "jaccard", ... ] },
        { type: "uc", algorithms: [ "jaccard", ... ] },
        ....
    ]
}

POST Perform comparison.

Calculate similarities of the given birthmarks. The birthmarks are posted in the request body.

Parameters

• algorithm (mandatory)
  • query parameter.
• birthmarks (mandatory)
  • request body.

Status code

• 202 Accepted
• 404 Not Found
  • The algorithm was not specified in the query parameter.
  • Given birthmarks were not available.
    • No birthmarks were given.
• 400 Bad request
  • Given birthmarks were invalid.
    • The birthmarks in the request body have multiple birthmark types.
    • Unknown birthmark types.
  • Given algorithm parameter was not suitable for given birthmarks.

Example of request body

{
    array: [ { 
       class-names: [
           { id: 1, class-name: "fully/qualified/class/name", source: "load/from" },
           ...
       ],
       extraction-results: { // this element is included the results is "extraction".
           type: "kgram",
           parameters: { k: 2 },
           birthmarks: [ {
               id: 1,
               elements: [ "8934", "afaf", ... ]
           }, ... ]
       }
    }, 
    ....
    ]
}

The format of request is the array of the results in the /api/results/{id}?key={key}.

Response Example

The request is allowed and success, the status code is 202 (Accepted), and respond json. The response contains the result url, key, status and expired date. Because, the birthmark comparison needs much time, likes the extraction.

{
    result_url: "http://hostname/pochi/api/results/{id}?key={key}",
    status: working, // preparing, working, or done
    expire: "2018-10-20T24:00:00.000Z"
}

/api/results/{id}?key={key}

GET

This endpoint responds the result of pochi. The query param {key} was required. The {id} and {key} are presented by the response of /api/birthmarks/{type} or api/similarities.

Status code

• 200 OK
  • Given {id} and {key} were matched.
• 404 Not Found
  • Given {id} was not found.
  • The result corresponded the given {id} have been deleted.
  • The result corresponded the given {id} was expired.
• 400 Bad Request
  • Given {id} and {key} were not matched.

Response Example

{
    status: "done", // preparing, working, or done
    results: "extraction", // extraction, or comparison
    expire: "2018-10-20T24:00:00.000Z",
    class-names: [
        { id: 1, class-name: "fully/qualified/class/name", source: "load/from/" },
        ...
    ],
    extraction-results: { // this element is included the results is "extraction".
        type: "kgram",
        parameters: { k: 2 },
        birthmarks: [ {
            id: 1,
            elements: [ "8934", "afaf", ... ]
        }, ... ]
    },
    comparison-results: { // this element is included the results is "comparison".
        type: "kgram",
        parameters: { k: 2 },
        algorithm: "comparison_algorithm",
        similarities: [
            { id1: 1, id2: 2, similarity: 0.78 },
        ]
    }
}

UPDATE

Update expire date to one week later of requested date.

Status code

• 200 OK
  • Given {id} and {key} were matched.
• 404 Not Found
  • Given {id} was not found.
  • The result corresponded the given {id} have been deleted.
  • The result corresponded the given {id} was expired.
• 400 Bad Request
  • Given {id} and {key} were not matched.

Response Example

{
    status: "done", // preparing, working, or done
    results: "extraction", // extraction, or comparison
    expire: "2018-10-20T24:00:00.000Z",
    class-names: [
        { id: 1, class-name: "fully/qualified/class/name", source: "load/from/" },
        ...
    ],
    extraction-results: { // this element is included the results is "extraction".
        type: "kgram",
        parameters: { k: 2 },
        birthmarks: [ {
            id: 1,
            elements: [ "8934", "afaf", ... ]
        }, ... ]
    },
    comparison-results: { // this element is included the results is "comparison".
        type: "kgram",
        parameters: { k: 2 },
        algorithm: "comparison_algorithm",
        similarities: [
            { id1: 1, id2: 2, similarity: 0.78 },
        ]
    }
}

This response is same as the response on GET.

DELETE

Delete the result actively.

Status code

• 200 OK
  • Always success.

Response Example

No response.