Skip to content

Latest commit

 

History

History
807 lines (697 loc) · 19.9 KB

README.md

File metadata and controls

807 lines (697 loc) · 19.9 KB
Raw

🌐 SimbirSoft Web API in brief

A RESTful API service for a centralized database of past records, facilitating multi-year experiments, animal migrations, and environmental tracking. Tested with a Docker image.

📜 Legend

Our company "Drip-Chip" is engaged in the chip-tracking of animals in the country "Wonderland" to monitor their movements and life cycles. Movement of animals on the planet is extremely important, including to protect them from extinction.

This year, our company decided to create a unified base, where the records of previous years will be transferred, for conducting long-term experiments related to animal migrations, as well as for tracking changes in habitats and keeping a history.

🔧 System Functionality Task

The system should have the following components:

Account

  • Role
  • Animal
  • Animal Type
  • Location Point
  • Animal Visited Location
  • Area
  • Area Analytics

The following functionality should be available in the controllers:

Authentication:

  • Account registration

Account:

  • View account information
  • Search/change/delete account

Animal:

  • View animal information
  • Search/create/change/delete animal
  • Create/change/delete animal type

Animal Type:

  • View animal type information
  • Create/change/delete animal type

Location Point:

  • View location point information
  • Create/change/delete location point

Animal Visited Location:

  • View animal movement information
  • Create/change/delete animal's location point

Area:

  • View area information
  • Create/change/delete area

Area Analytics:

  • View animal movements in the area

At the first launch of the application, the following accounts are automatically created in the database:

{
  "id": 1,				// User account identifier
  "firstName": "adminFirstName",	// User's first name
  "lastName": "adminLastName",	        // User's last name
  "email": "admin@simbirsoft.com",	// User's email address
  "password": "qwerty123",		// User's account password
  "role": "ADMIN"			// User's account role
},
{
  "id": 2,			        // User account identifier
  "firstName": "chipperFirstName",	// User's first name
  "lastName": "chipperLastName",	// User's last name
  "email": "chipper@simbirsoft.com",	// User's email address
  "password": "qwerty123",		// User's account password
  "role": "CHIPPER"			// User's account role
},
{
  "id": 3,				// User account identifier
  "firstName": "userFirstName",		// User's first name
  "lastName": "userLastName",		// User's last name
  "email": "user@simbirsoft.com",	// User's email address
  "password": "qwerty123",		// User's account password
  "role": "USER"			// User's account role
}

🐾 API Declarations

1) User authentication

API 1: Register a new account

Endpoint: POST /registration

Request:

{
  "firstName": "string",  // User's first name
  "lastName": "string",   // User's last name
  "email": "string",      // Email address
  "password": "string"    // User's account password
}

Response:

{
  "id": "int",            // User's account ID
  "firstName": "string",  // User's first name
  "lastName": "string",   // User's last name
  "email": "string",      // Email address
  "role": "string"        // User's account role, defaults to "USER" upon registration
}

2) User account

API 1: Get user account information

Endpoint: GET /accounts/{accountId}

Request:

{
// No request body
}

Response:

{
 "id": "int",           // User's account ID
 "firstName": "string", // User's first name
 "lastName": "string",  // User's last name
 "email": "string",     // Email address
 "role": "string"       // User's account role, defaults to "USER" upon registration
}

API 2: Search user accounts

Endpoint: GET /accounts/search/?firstName={firstName}&lastName={lastName}&email={email}&from={from}&size={size}

Request:

{
 // No request body
}

Response:

[
 {
  "id": "int",          // User's account ID
  "firstName": "string", // User's first name
  "lastName": "string", // User's last name
  "email": "string",    // Email address
  "role": "string"      // User's account role, defaults to "USER" upon registration
 }
]

API 3: Add a new user account

Endpoint: POST /accounts

Request:

{
 "firstName": "string", // User's first name
 "lastName": "string",  // User's last name
 "email": "string",     // Email address
 "password": "string",  // User's account password
 "role": "string"       // User's account role, available values "ADMIN", "CHIPPER", "USER"
}

Response:

{
 "id": "int",           // User's account ID
 "firstName": "string", // User's first name
 "lastName": "string",  // User's last name
 "email": "string",     // Email address
 "role": "string"       // User's account role
}

API 4: Update user account information

Endpoint: PUT /accounts/{accountId}

Request:

{
 "firstName": "string", // New user's first name
 "lastName": "string",  // New user's last name
 "email": "string",     // New email address
 "password": "string",  // New user's account password
 "role": "string"       // New user's account role, available values "ADMIN", "CHIPPER", "USER"
}

Response:

{
 "id": "int",           // User's account ID
 "firstName": "string", // New user's first name
 "lastName": "string",  // New user's last name
 "email": "string",     // New email address
 "role": "string"       // New user's account role
}

API 5: Delete a user account

Endpoint: DELETE /accounts/{accountId}

Request:

{
 // No request body
}

Response:

{
 // No response body
}

3) Animal Location Point

API 1: Get animal location point information

Endpoint: GET /locations/{pointId}

Request:

{
 // No request body
}

Response:

{
 "id": "long",          // Location point ID
 "latitude": "double",  // Geographic latitude in degrees
 "longitude": "double"  // Geographic longitude in degrees
}

API 2: Add a new animal location point

Endpoint: POST /locations

Request:

{
 "latitude": "double",  // Geographic latitude in degrees
 "longitude": "double"  // Geographic longitude in degrees
}

Response:

{
 "id": "long",          // Location point ID
 "latitude": "double",  // Geographic latitude in degrees
 "longitude": "double"  // Geographic longitude in degrees
}

API 3: Update animal location point information

Endpoint: PUT /locations/{pointId}

Request:

{
 "latitude": "double",  // New geographic latitude in degrees
 "longitude": "double"  // New geographic longitude in degrees
}

Response:

{
 "id": "long",          // Location point ID
 "latitude": "double",  // New geographic latitude in degrees
 "longitude": "double"  // New geographic longitude in degrees
}

API 4: Delete an animal location point

Endpoint: DELETE /locations/{pointId}

Request:

{
 // No request body
}

Response:

{
 // No response body
}

4) Zones

API 1: Get zone information

Endpoint: GET /areas/{areaId}

Request:

{
 // No request body
}

Response:

{
 "id": "long",         // Zone ID
 "name": "string",     // Zone name
 "areaPoints": [
   {
    "longitude": "double", // Geographic longitude in degrees
    "latitude": "double"  // Geographic latitude in degrees
   },
 ]
}

API 2: Add a new zone

Endpoint: POST /areas

Request:

{
 "name": "string",     // Zone name
 "areaPoints": [
   {
    "longitude": "double", // Geographic longitude in degrees
    "latitude": "double"  // Geographic latitude in degrees
   },
 ]
}

Response:

{
 "id": "long",         // Zone ID
 "name": "string",     // Zone name
 "areaPoints": [
   {
    "longitude": "double", // Geographic longitude in degrees
    "latitude": "double"  // Geographic latitude in degrees
   },
 ]
}

API 3: Update zone information

Endpoint: PUT /areas/{areaId}

Request:

{
 "name": "string",     // Zone name
 "areaPoints": [
   {
    "longitude": "double", // Geographic longitude in degrees
    "latitude": "double"  // Geographic latitude in degrees
   },
 ]
}

Response:

{
 "id": "long",         // Zone ID
 "name": "string",     // Zone name
 "areaPoints": [
   {
    "longitude": "double", // Geographic longitude in degrees
    "latitude": "double"  // Geographic latitude in degrees
   },
 ]
}

API 4: Delete a zone

Endpoint: DELETE /areas/{areaId}

Request:

{
 // No request body
}

Response:

{
 // No response body
}

5) Animal Types

API 1: Get animal type information

Endpoint: GET /animals/types/{typeId}

Request:

{
 // No request body
}

Response:

{
 "id": "long",        // Animal type ID
 "type": "string"     // Animal type
}

API 2: Add a new animal type

Endpoint: POST /animals/types

Request:

{
 "type": "string"     // Animal type
}

Response:

{
 "id": "long",        // Animal type ID
 "type": "string"     // Animal type
}

API 3: Update animal type information

Endpoint: PUT /animals/types/{typeId}

Request:

{
 "type": "string"     // New animal type
}

Response:

{
 "id": "long",        // Animal type ID
 "type": "string"     // New animal type
}

API 4: Delete an animal type

Endpoint: DELETE /animals/types/{typeId}

Request:

{
 // No request body
}

Response:

{
 // No response body
}

1) Animals

API 1: Get animal information

Endpoint: GET /animals/{animalId}

Request:

{
 // No request body
}

Response:

{
 "id": "long",                     // Animal ID
 "animalTypes": "[long]",           // Array of animal type IDs
 "weight": "float",                // Animal weight in kg
 "length": "float",                // Animal length in m
 "height": "float",                // Animal height in m
 "gender": "string",                // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",            // Animal life status (ALIVE, DEAD)
 "chippingDateTime": "dateTime",    // Animal chipping date and time in ISO-8601 format
 "chipperId": "int",                // Chipper account ID
 "chippingLocationId": "long",      // Animal chipping location ID
 "visitedLocations": "[long]",      // Array of visited location IDs
 "deathDateTime": "dateTime"        // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
}

API 2: Search animals by parameters

Endpoint: GET /animals/search?startDateTime={startDateTime}&endDateTime={endDateTime}&chipperId={chipperId}&chippingLocationId={chippingLocationId}&lifeStatus={lifeStatus}&gender={gender}&from=0&size=10

Request:

{
 // No request body
}

Response:

[
 {
  "id": "long",                     // Animal ID
  "animalTypes": "[long]",           // Array of animal type IDs
  "weight": "float",                // Animal weight in kg
  "length": "float",                // Animal length in m
  "height": "float",                // Animal height in m
  "gender": "string",                // Animal gender (MALE, FEMALE, OTHER)
  "lifeStatus": "string",            // Animal life status (ALIVE, DEAD)
  "chippingDateTime": "dateTime",    // Animal chipping date and time in ISO-8601 format
  "chipperId": "int",                // Chipper account ID
  "chippingLocationId": "long",      // Animal chipping location ID
  "visitedLocations": "[long]",      // Array of visited location IDs
  "deathDateTime": "dateTime"        // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
 }
]

API 3: Add a new animal

Endpoint: POST /animals

Request:

{
 "animalTypes": "[long]",           // Array of animal type IDs
 "weight": "float",                // Animal weight in kg
 "length": "float",                // Animal length in m
 "height": "float",                // Animal height in m
 "gender": "string",                // Animal gender (MALE, FEMALE, OTHER)
 "chipperId": "int",                // Chipper account ID
 "chippingLocationId": "long"       // Animal chipping location ID
}

Response:

{
 "id": "long",                     // Animal ID
 "animalTypes": "[long]",           // Array of animal type IDs
 "weight": "float",                // Animal weight in kg
 "length": "float",                // Animal length in m
 "height": "float",                // Animal height in m
 "gender": "string",                // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",            // Animal life status (ALIVE, DEAD)
 "chippingDateTime": "dateTime",    // Animal chipping date and time in ISO-8601 format
 "chipperId": "int",                // Chipper account ID
 "chippingLocationId": "long",      // Animal chipping location ID
 "visitedLocations": "[long]",      // Array of visited location IDs
 "deathDateTime": "dateTime"        // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
}

API 4: Update animal information

Endpoint: PUT /animals/{animalId}

Request:

{
 "weight": "float",                // Animal weight in kg
 "length": "float",                // Animal length in m
 "height": "float",                // Animal height in m
 "gender": "string",                // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",            // Animal life status (ALIVE, DEAD)
 "chipperId": "int",                // Chipper account ID
 "chippingLocationId": "long"       // Animal chipping location ID
}

Response:

{
 "id": "long",                     // Animal ID
 "animalTypes": "[long]",           // Array of animal type IDs
 "weight": "float",                // Animal weight in kg
 "length": "float",                // Animal length in m
 "height": "float",                // Animal height in m
 "gender": "string",                // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",            // Animal life status (ALIVE, DEAD)
 "chippingDateTime": "dateTime",    // Animal chipping date and time in ISO-8601 format
 "chipperId": "int",                // Chipper account ID
 "chippingLocationId": "long",      // Animal chipping location ID
 "visitedLocations": "[long]",      // Array of visited location IDs
 "deathDateTime": "dateTime"        // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
}

API 5: Delete an animal

Endpoint: DELETE /animals/{animalId}

Request:

{
 // No request body
}

Response:

{
 // No response body
}

API 6: Add an animal type to an animal

Endpoint: POST /animals/{animalId}/types/{typeId}

Request:

{
 // No request body
}

Response:

{
 "id": "long",                   // Animal ID
 "animalTypes": "[long]",          // Array of animal type IDs
 "weight": "float",               // Animal weight in kg
 "length": "float",               // Animal length in m
 "height": "float",               // Animal height in m
 "gender": "string",               // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",           // Animal life status (ALIVE, DEAD)
 "chippingDateTime": "dateTime",   // Animal chipping date and time in ISO-8601 format
 "chipperId": "int",               // Chipper account ID
 "chippingLocationId": "long",     // Animal chipping location ID
 "visitedLocations": "[long]",     // Array of visited location IDs
 "deathDateTime": "dateTime"       // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
}

API 7: Change the animal type of an animal

Endpoint: PUT /animals/{animalId}/types

Request:

{
 "oldTypeId": "long", 			// Current animal type ID
 "newTypeId": "long" 			// New animal type ID for replacement
}

Response:

{
 "id": "long",                   // Animal ID
 "animalTypes": "[long]",          // Array of animal type IDs
 "weight": "float",               // Animal weight in kg
 "length": "float",               // Animal length in m
 "height": "float",               // Animal height in m
 "gender": "string",               // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",           // Animal life status (ALIVE, DEAD)
 "chippingDateTime": "dateTime",   // Animal chipping date and time in ISO-8601 format
 "chipperId": "int",               // Chipper account ID
 "chippingLocationId": "long",     // Animal chipping location ID
 "visitedLocations": "[long]",     // Array of visited location IDs
 "deathDateTime": "dateTime"       // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
}

API 8: Delete the animal type of an animal

Endpoint: DELETE /animals/{animalId}/types/{typeId}

Request:

{
 // No request body
}

Response:

{
 "id": "long",                   // Animal ID
 "animalTypes": "[long]",          // Array of animal type IDs
 "weight": "float",               // Animal weight in kg
 "length": "float",               // Animal length in m
 "height": "float",               // Animal height in m
 "gender": "string",               // Animal gender (MALE, FEMALE, OTHER)
 "lifeStatus": "string",           // Animal life status (ALIVE, DEAD)
 "chippingDateTime": "dateTime",   // Animal chipping date and time in ISO-8601 format
 "chipperId": "int",               // Chipper account ID
 "chippingLocationId": "long",     // Animal chipping location ID
 "visitedLocations": "[long]",     // Array of visited location IDs
 "deathDateTime": "dateTime"       // Animal death date and time in ISO-8601 format (null while lifeStatus is ALIVE)
}

7) Location point visited by the animal

API 1: View location points visited by the animal

Endpoint: GET /animals/{animalId}/locations?startDateTime=&endDateTime=&from={from}&size={size}

Request:

{
 // No request body
}

Response:

[
 { 
 "id": "long",                 // ID of the location object
 "dateTimeOfVisitLocationPoint": "dateTime", // Date and time of the location visit in ISO-8601 format
 "locationPointId": "long"     // ID of the visited location point
 }
]

API 2: Add a location point visited by an animal

Endpoint: POST /animals/{animalId}/locations/{pointId}

Request:

{
 // No request body
}

Response:

{ 
 "id": "long",                 // ID of the location object
 "dateTimeOfVisitLocationPoint": "dateTime", // Date and time of the location visit in ISO-8601 format
 "locationPointId": "long"     // ID of the visited location point
}

API 3: Change the location point visited by the animal

Endpoint: PUT /animals/{animalId}/locations

Request:

{
 // No request body
}

Response:

{ 
 "id": "long",                 // ID of the location object
 "dateTimeOfVisitLocationPoint": "dateTime", // Date and time of the location visit in ISO-8601 format
 "locationPointId": "long"     // ID of the visited location point
}

API 4: Deleting a location visited by an animal

Endpoint: DELETE /animals/{animalId}/locations/{visitedPointId}

Request:

{
 // No request body
}

Response:

{ 
 // No response body
}

8) Zone analytics

API 1: View animal movement information in a zone

Endpoint: GET /areas/{areaId}/analytics?startDate=&endDate=

Request:

{
 // No request body
}

Response:

{ 
 "totalQuantityAnimals": "long", 	// Total number of animals in this zone during the specified time interval
 "totalAnimalsArrived": "long", 	// Total number of visits to the zone during the specified time interval
 "totalAnimalsGone": "long", 		// Total number of exits from the zone during the specified time interval
 "animalsAnalytics": [ 
   {
     "animalType": "string", 	// Type of animals
     "animalTypeId": "long", 	// ID of animal types
     "quantityAnimals": "long", 	// Number of animals of this type in this zone during the specified time interval
     "animalsArrived": "long", 	// Number of animals of this type that arrived in this zone during the specified time interval
     "animalsGone": "long", 	// Number of animals of this type that left this zone during the specified time interval
   }
 ]
}