Skip to content

API Documentation

Jump to bottom
Vishal edited this page May 3, 2021 · 39 revisions

Description

The FastAPI service provides auto-generated documentation of our API, but here is a more in-depth summary. The API runs on Docker and is used to process incoming requests to the web application, and the Elasticsearch index. If you would like to see these calls in action, try running the Python calls made here: assess_api_calls.py. Before running the script, make sure you change these lines with the correct username, password, and URL to authenticate, located in conf.yaml. There is also one line in the assess_api_calls.py that assigns a PDF to a variable used by certain endpoints. You can customize this reference to a demo Statement of Work in PDF format from your local machine by changing that line here. After changing the reference and using the right config values, you'll be able to run this script to completion. Below shows the details for each of the API calls being made.

POST /recommend_text

  • Given an input of a complete or partial Statement of Work (SoW) as text, return a JSON of recommended standards. You can also add a size variable to this using /recommend_text?size=YOUR_SIZE where YOUR_SIZE is the number of results you want returned. Right now this number defaults to 10.

Example input:

{
  "text_field": "Airplanes are complex."
}

Each recommend endpoint returns a JSON of the results found. These have a key each for the result (the key is a digit ranking the standard's relevance). Each result is ranked in descending relevance (1 through 10) and is given a similarity score, a score outputted by the machine learning algorithm doing document ranking based on the input. The similarity is a key provided alongside the results, outlined below. The value of the key similarity is a float between 0.0 and 100.0. Results are listed in order of their relevance.

Example output:

{
"1":{RESULT, "similarity":35.0,}, 
"2":{RESULT, "similarity":20.0,} 
}

POST /recommend_file

  • Given an SoW as a PDF, return a JSON of recommended standards.

Example input: JSON payload is sent as files={"pdf": pdf object}

Example output: The output should be in the same format as the recommend_textendpoint described above.

POST /extract

  • Given an SoW as a PDF, return a JSON of extracted standards that are embedded within the SoW. the /recommend endpoints do this implicitly, however, this is the isolated functionality for extraction alone.

Example output:

{
    "embedded_references": [
        "ISO 9001:2015",
        "ISO 9001:2000",
        "ISO 10019",
        "ISO 9004",
        "ISO 10003",
        "ISO 10002",
        "ISO 10008",
        "ISO 9000",
        "ISO 2015",
        "ISO 31000",
        "ISO 10014",
        "ISO 9000:2015",
        "ISO/TR 10017",
        "ISO 37500",
        "ISO 10001",
        "ISO 9001:2008",
        "ISO 10005",
        "ISO 19011",
        "ISO1) [28]",
        "ISO 10015",
        "ISO/TR 10013",
        "ISO/IEC 90003",
        "ISO1) 1)",
        "ISO 9001",
        "ISO/TC 176/SC",
        "ISO 9001:2015(E)",
        "ISO 10007",
        "(ISO 9001:2008)",
        "ISO 9001:2008/Cor.1:2009",
        "ISO 10004",
        "IEC 60300-1",
        "IEC 61160",
        "ISO 10012",
        "ISO 14001",
        "ISO 10006",
        "ISO 10018",
        "ISO/TC 176"
    ],
    "filename": "test2.pdf"
}

GET /standard_info/

  • Given a standard field, return the standard information from Elasticsearch. You can search by id, raw_id, isbn, doc_number, technical committee, status, published_date, ingestion_date, title, hash, and sdo individually as a query parameter. You can also specify a size for the query in the results. You can read more about what these keys specifically refer to by reading about our database scheme here.

Example GET requests placing the query string within the request:

Return field id with a value of "A123456Z" and return 1 result.

  • /standard_info/?id=A123456Z

Return field raw_id with a value of "ICS-TEST" and return 1 result.

  • /standard_info/?raw_id=ICS-TEST

Return field doc_number with a value of "200" and return 1 result.

  • /standard_info/?doc_number=200

Return field Status with a value of "Published" and return 10 results.

  • /standard_info/?status=Published&size=10

Return with field sdo containing an inner object data as a key and return 10 results.

  • /standard_info/?sdo=ics&size=10

Example response for /standard_info/?id=x0288b9ed144439f8ad8fa017d604eac:

{
    "1": {
        "id": "x0288b9ed144439f8ad8fa017d604eac",
        "raw_id": "ISO 44-2:2015",
        "description": "ISO 000 is a dummy standard I am adding that is made up.",
        "ingestion_date": "2018-03-10 13:07:45",
        "hash": "7c8dc19cfbb38a573090c4b0b2c6d3b4f4d68f98ed55506aed936f78cfc71590",
        "published_date": "2020-12",
        "isbn": null,
        "text": [
            "description"
        ],
        "status": "TO_DELETE",
        "technical_committee": "ISO/TC 1111",
        "title": "This is dummy data",
        "url": "https://www.iso.org/standard/123123.html",
        "category": {
            "ics": "['43.060.20']"
        },
        "sdo": {
            "abbreviation": "iso",
            "data": {
                "code": "0.30.010.10.ISO/IEC 10592:1992",
                "edition": [
                    2
                ],
                "field": "1",
                "group": "1.1",
                "number_of_pages": [
                    1
                ],
                "preview_url": "https://www.iso.org/obp/ui/#!iso:std:123123:en",
                "section_titles": [
                    "Foreword",
                    "Introduction",
                    "1   Scope",
                    "2   Normative references",
                    "3   Terms and definitions"
                ],
                "sections": null,
                "subgroup": "1.1.1",
                "type": "standard"
            }
        }
    }
}

}

GET /search/{searchq}

Example input searching description for string "airplane technology" and returning 3 results.:

/airplanes%20technology&size=3",

PUT /add_standards

  • Add standards to the main Elasticsearch index by sending a PUT request here. Here is an example dummy standard we successfully added using the script. It may be useful to reference: https://github.com/nasa-jpl/ASSESS/wiki/Elasticsearch for understanding the details of the fields.

Example input:

{
        "id": "ece24a82902c4de7b854c9b6e91d4ad4",
        "raw_id": "ISO/FDIS 00000-3",
        "doc_number": 10000,
        "description": "",
        "status": "Under development",
        "technical_committee": "ISO/TC 000",
        "sdo": {
            "abbreviation": "iso",
            "data": {
                "code": "0.11.000.00.ISO/FDIS 18250-3",
                "field": "11",
                "group": "11.000",
                "subgroup": "11.000.25",
                "edition": [
                    1
                ],
                "number_of_pages": [
                    0
                ],
                "section_titles": [],
                "sections": [],
                "type": "standard",
                "preview_url": ""
            }
        },
        "category": {
            "ics": "['11.000.00']"
        },
        "text": [
            "description",
            "title"
        ],
        "title": "Connectors for reservoir delivery systems for healthcare applications -- Part 3: Enteral applications",
        "published_date": "",
        "isbn": null,
        "url": "https://www.iso.org/standard/0000.html",
        "ingestion_date": "2018-03-10 05:20:27",
        "hash": null
    }

POST /select_standards

  • After a user selects a standard, this endpoint captures the selected standards into the database. Selecting a standard is an end user functionality that we define as a user saying that a recommended or extracted standard will be used by the user. This becomes useful for admin statistics.

Example input:

selected = {
    "username": "test_user",
    "selected_ids": ["A123456Z"],
}

PUT /set_standards

  • Manually update the preference of standards (done by an Admin). This functionality is for the admin to set the priority weights of a standard's relevance. Priority weights at the moment are a number between 1-100, 100 being the highest priority. An admin's PUT request would be a simple JSON stating their username, the standard ID, and the priority being set to the standard. Once the priority is set, whenever the standard is recommended, we highlight this standard as having priority. This feature requires some feedback from an admin, to understand their specific needs and is placed here at the moment as a demonstration of the workflow.

Example input:

set_standards = {
    "username": "test_user",
    "standard_id": "A123456Z",
    "priority": 100,
}
Clone this wiki locally