RESTful API – projektowanie pierwszego endpointa

Jeśli programujesz w Javie, wcześniej czy później spotkasz się z potrzebą stworzenia API. Możesz mieć aplikację desktopową, która musi wysyłać dane do serwera, albo stronę internetową, która pobiera informacje z bazy danych. W obu przypadkach REST API jest najbardziej popularnym rozwiązaniem.

Dlaczego REST API jest ważne

REST (Representational State Transfer) to architektoniczny styl projektowania API, który wykorzystuje standardowe metody HTTP. Zamiast wymyślać własny protokół komunikacji, używasz tego co już istnieje – GET do pobierania danych, POST do dodawania, PUT do aktualizacji, DELETE do usuwania.

Czym dokładnie jest REST API

REST API składa się z kilku kluczowych elementów:

• Endpoint – konkretny adres URL, pod którym dostępna jest usługa
• Metoda HTTP – określa co chcemy zrobić (GET, POST, PUT, DELETE)
• Request – żądanie wysłane przez klienta
• Response – odpowiedź serwera, zwykle w formacie JSON

Pierwszy projekt Spring Boot

Spring Boot to framework, który znacznie upraszcza tworzenie aplikacji Java. W 2015 roku Spring Boot 1.2 wprowadził rewolucję – możesz stworzyć działającą aplikację web w kilka minut.

Konfiguracja projektu

Zacznij od stworzenia nowego projektu Maven z następującą strukturą:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>com.example</groupId>
    <artifactId>rest-api-demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.3.5.RELEASE</version>
        <relativePath/>
    </parent>
    
    <properties>
        <java.version>1.8</java.version>
    </properties>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

Główna klasa aplikacji

Stwórz klasę główną aplikacji:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class RestApiDemoApplication {
    
    public static void main(String[] args) {
        SpringApplication.run(RestApiDemoApplication.class, args);
    }
}

Tworzenie pierwszego endpointa

Teraz stwórzmy nasz pierwszy REST endpoint. Będzie to prosty serwis zwracający informacje o użytkowniku:

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {
    
    @GetMapping("/users/{id}")
    public User getUser(@PathVariable Long id) {
        // W prawdziwej aplikacji pobierałbyś dane z bazy
        User user = new User();
        user.setId(id);
        user.setName("Jan Kowalski");
        user.setEmail("jan.kowalski@example.com");
        return user;
    }
    
    @GetMapping("/users")
    public String getAllUsers() {
        return "Lista wszystkich użytkowników - endpoint w budowie";
    }
}

Klasa User (model danych)

package com.example.demo.model;

public class User {
    private Long id;
    private String name;
    private String email;
    
    // Konstruktor domyślny wymagany przez Jackson
    public User() {}
    
    // Gettery i settery
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

Podstawowe metody HTTP w praktyce

HTTP oferuje kilka metod, każda ma swoje przeznaczenie:

Rozszerzenie API o więcej metod

@RestController
public class UserController {
    
    // Symulujemy bazę danych prostą listą
    private List<User> users = new ArrayList<>();
    
    @GetMapping("/users/{id}")
    public User getUser(@PathVariable Long id) {
        return users.stream()
                   .filter(user -> user.getId().equals(id))
                   .findFirst()
                   .orElse(null);
    }
    
    @PostMapping("/users")
    public User createUser(@RequestBody User user) {
        user.setId(System.currentTimeMillis()); // Prosty generator ID
        users.add(user);
        return user;
    }
    
    @DeleteMapping("/users/{id}")
    public String deleteUser(@PathVariable Long id) {
        users.removeIf(user -> user.getId().equals(id));
        return "User deleted successfully";
    }
}

Testowanie API

Uruchom aplikację komendą mvn spring-boot:run lub przyciskiem Run w IDE. Spring Boot uruchomi embedded Tomcat na porcie 8080.

Testowanie w przeglądarce

Wpisz w przeglądarce:

• http://localhost:8080/users/1 – sprawdzi endpoint GET
• http://localhost:8080/users – sprawdzi listę użytkowników

Testowanie z curl (wiersz poleceń)

# GET - pobieranie użytkownika
curl http://localhost:8080/users/1

# POST - tworzenie nowego użytkownika  
curl -X POST http://localhost:8080/users \
     -H "Content-Type: application/json" \
     -d '{"name":"Anna Nowak","email":"anna@example.com"}'

# DELETE - usuwanie użytkownika
curl -X DELETE http://localhost:8080/users/1

Najlepsze praktyki projektowania URL-i

URL w REST API powinien być intuicyjny i logiczny. Oto zasady które warto stosować:

Obsługa błędów

W prawdziwej aplikacji rzeczy mogą pójść nie tak. Oto jak obsłużyć podstawowe błędy:

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = users.stream()
                    .filter(u -> u.getId().equals(id))
                    .findFirst()
                    .orElse(null);
    
    if (user == null) {
        return ResponseEntity.notFound().build(); // HTTP 404
    }
    
    return ResponseEntity.ok(user); // HTTP 200
}

Common mistakes – błędy początkujących

Przydatne zasoby:

• Spring Boot REST Service Guide
• Spring MVC Documentation
• JSON Format Specification
• HTTP Status Codes Reference

Masz pytania o REST API w Spring Boot? Podziel się swoimi doświadczeniami w komentarzach – chętnie pomogę rozwiązać problemy!