Employee Management REST API

A comprehensive RESTful API for managing employee data with built-in pagination, sorting, and hypermedia support using HAL+JSON format.

🚀 Features

• Full CRUD Operations - Create, Read, Update, and Delete employees
• Pagination Support - Efficient handling of large datasets
• Flexible Sorting - Multiple sort criteria with ascending/descending options
• HAL+JSON Compliance - Hypermedia-driven API with discoverable links
• Spring Boot Integration - Built with Spring Data REST for rapid development
• Profile Endpoints - API discoverability and metadata

📋 Table of Contents

• Getting Started
• API Endpoints
• Request/Response Examples
• Data Models
• Error Handling
• Contributing

🏃 Getting Started

Prerequisites

• Java 11 or higher
• Maven 3.6+
• Spring Boot 2.5+

Installation

1. Clone the repository

git clone <your-repository-url>
cd employee-management-api

2. Build the project

mvn clean install

3. Run the application

mvn spring-boot:run

The API will be available at http://localhost:8080

API Documentation

Interactive API documentation is available at:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI Spec: http://localhost:8080/v3/api-docs

🛠 API Endpoints

Employee Management

Method	Endpoint	Description
GET	/magic-api/members	List all employees (paginated)
POST	/magic-api/members	Create a new employee
GET	/magic-api/members/{id}	Get employee by ID
PUT	/magic-api/members/{id}	Update employee (full replacement)
PATCH	/magic-api/members/{id}	Partial update of employee
DELETE	/magic-api/members/{id}	Delete employee

Profile & Discovery

Method	Endpoint	Description
GET	/magic-api/profile	Get API profile information
GET	/magic-api/profile/members	Get members resource profile

📝 Request/Response Examples

Get All Employees

GET /magic-api/members?page=0&size=10&sort=lastName,asc HTTP/1.1
Host: localhost:8080
Accept: application/hal+json

Response:

{
  "_embedded": {
    "employees": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "_links": {
          "self": {
            "href": "http://localhost:8080/magic-api/members/1"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/magic-api/members?page=0&size=10"
    },
    "next": {
      "href": "http://localhost:8080/magic-api/members?page=1&size=10"
    }
  },
  "page": {
    "size": 10,
    "totalElements": 25,
    "totalPages": 3,
    "number": 0
  }
}

Create New Employee

POST /magic-api/members HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com"
}

Update Employee

PUT /magic-api/members/1 HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe.updated@example.com"
}

🏗 Data Models

Employee

Field	Type	Required	Description
firstName	String	Yes	Employee's first name
lastName	String	Yes	Employee's last name
email	String	Yes	Employee's email address

Pagination Parameters

Parameter	Type	Default	Description
page	Integer	0	Zero-based page index
size	Integer	20	Number of items per page
sort	String[]	-	Sort criteria: property,(asc|desc)

📊 Response Formats

The API supports multiple response formats:

• application/hal+json (default) - HAL hypermedia format
• application/x-spring-data-compact+json - Compact Spring Data format
• text/uri-list - URI list format

❌ Error Handling

The API returns standard HTTP status codes:

• 200 OK - Successful GET, PUT, PATCH
• 201 Created - Successful POST
• 204 No Content - Successful DELETE
• 400 Bad Request - Invalid request data
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Error responses follow the standard format:

{
  "timestamp": "2024-01-15T10:15:30.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/magic-api/members"
}

🔧 Configuration

Application Properties

# Server Configuration
server.port=8080

# Database Configuration
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.jpa.hibernate.ddl-auto=update

# HAL Configuration
spring.data.rest.base-path=/magic-api
spring.data.rest.default-page-size=20
spring.data.rest.max-page-size=100

🧪 Testing

Run the test suite:

mvn test

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

👤 Author

Created and maintained by [Shivansh Pal]

🙏 Acknowledgments

• Spring Boot team for the excellent framework
• Spring Data REST for hypermedia support
• OpenAPI for API documentation standards

---

For questions or support, please open an issue in the repository.