NASA InSight Weather Java API wrapper

Java API wrapper for NASA's InSight: Mars Weather Service API.

Based on the Spring Boot RESTful web service.

Functionality

Requests

The API offers only one endpoint: /nasa/temperature, which can be called to obtain the average Mars temperature using the data provided by NASA's API.

Two optional parameters are available:

sol - It can be used to specify the sol to retrieve the average temperature. If data for the sol is not available, 404 Not Found error is returned. If not specified, the average for all available sols (usually past 7 days) is returned.
force_cache_expire - Forces the API to clear any cached data before serving the request.

Example call for sol 430, with local API running on localhost:8080:

    GET http://localhost:8080/nasa/temperature?sol=430&force_cache_expire=true

Responses

The responses are formatted as JSON. On a successful request, the response contains the following fields:

status_code - Status code for the HTTP request (usually 200).
message - Additional information regarding the response data.
average_temperature - Average temperature retrieved. Rounded to 3 decimal places.
sol_keys - The sols used for calculating the average temperature.

On a failed request, the response contains the following fields:

status_code - Either 404 for unavailable sol, or 500 for unexpected errors.
error - Error name.
message - Error description.

Example for successful request for sol 430:

{ 
    "sol_keys": [430],
    "average_temperature": -61.245,
    "status_code": 200,
    "message": "Request successful."
}

Example for successful request with no specified sol:

{ 
    "sol_keys": [427, 428, 429, 430, 431, 432, 433],
    "average_temperature": -60.886,
    "status_code": 200,
    "message": "Request successful."
}

Example for failed request for unavailable sol:

{ 
    "error": "NotFound",
    "status_code": 404,
    "message": "Sol key not found. Available sol keys: [427, 428, 429, 430, 431, 432, 433]."
}

Implementation Details

All of the top-level logic takes place inside the API controller com.nasa.api.NasaApiController.

Interfacing with the NASA API is done by com.nasa.api.InSightWeatherApi.

The models and JSON deserialization for handling the incoming data from NASA's API are implemented by the packages com.nasa.api.model and com.nasa.api.deserialization, respectively.

The data handling for interfacing with users of the API is implemented on the com.nasa.api.response package.

This implementation also offers basic in-memory caching features (com.nasa.api.Cache), which means not all calls to this API cause a request to be sent to NASA's API, improving performance.

Running

Running requires JDK 13. Make sure the JAVA_HOME environment variable is set correctly.

To run the program, first clone and open the repository:

    git clone https://github.com/gabrieljablonski/nasa-api.git
    cd /nasa-api

On Linux, prepare the maven script and run it:

    sudo chmod +x ./mvnw
    sudo ./mvnw spring-boot:run

On Windows, simply run the script:

    .\mvnw spring-boot:run

Wait for the dependencies to be fetched. The project will then be compiled and run.

When started, the API can be accessed by opening a browser and going to http://localhost:8080/nasa/temperature. The optional parameters can then be set as described in the Functionality section.

API Parameters Customization

The application.properties file presents 3 parameters that can be customized, described below.

server.port - The port the API will run on (defaults to 8080).
nasa.api.key - The API key that will be used on requests to NASA's API (defaults to DEMO_KEY).
nasa.api.cache.expiration - The maximum time in seconds cached data will stay available (defaults to 600).

Other parameters should not be changed. After the new parameters are set, run the project again.

Automatized Testing

A testing script (automatic_testing.py) is available to test the three different types of responses:

No specified sol.
Sol specified and available.
Sol specified but unavailable.

The script requires Python 3.6+.

To run it, first change into the project directory and setup a virtual environment.

On Linux:

    cd /nasa-api
    python3 -m venv venv
    source ./venv/bin/activate
    python3 -m pip install -r requirements.txt

On Windows:

    cd .\nasa-api
    python -m venv venv
    .\venv\Scripts\activate
    python -m pip install -r requirements.txt

The script offers two optional command line arguments:

port - The port in which the local API is running (defaults to 8080).
api-key - The API key for making NASA API calls (defaults to DEMO_KEY).

Running on Linux:

    python3 ./automatic_testing.py --port 8080 --api-key DEMO_KEY