Advisory Program 2022 (Chapter 1) : Create Your First API

Prerequisites

• Java Development Kit (JDK) versi 11 or later (link)

• Maven (how to)

• IDE (sesuai preferensi)

• PostgreSQL, saya menggunakan versi 12 (link)

• Postman, opsional (link)

Disclaimer

Backend For Frontend

Why Java/Spring?

• Group: com.bca

• Artifact: adam

• Name, Description, Package Name: default

• Spring Web (komponen Spring utama yang kita butuhkan untuk membuat aplikasi Spring Web atau REST API dengan Spring)

• Spring Data JPA (diperlukan untuk berinteraksi dengan database tanpa harus membuat koneksi dan query secara manual)

• Lombok (sebuah library yang sangat berguna untuk memudahkan kita dalam menuliskan program Java, terutama untuk mempersingkat dan mengurangi redundansi yang tidak perlu)

• PostgreSQL Driver (driver yang diperlukan untuk koneksi ke database kita yaitu Postgres)

• Spring Boot Devtools (library ini akan memudahkan kita dalam proses development terutama untuk hot reload)

Getting started with Our API Development

.
├── .mvn
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com/bca/adam
│   │   │       ├── AdamApplication.java
│   │   │       └── ServletInitializer.java
│   │   └── resources
│   │       ├── static
│   │       ├── templates
│   │       └── application.properties
│   └── test
├── .gitignore
├── HELP.md
├── mvnw
├── mvnw.cmd
└── pom.xml

<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-data-jpa</artifactId>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
	...
</dependencies>

@SpringBootApplication
public class AdamApplication {

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

}

package com.bca.adam.controller;

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;

@RestController
@RequestMapping("hello")
public class HelloWorldController {

}

@RestController
@RequestMapping("hello")
public class HelloWorldController {

    @GetMapping
    public String index() {
        return "Hello World!";
    }

}

@RestController
@RequestMapping("hello")
public class HelloWorldController {

    @GetMapping
    public String index() {
        return "Hello World!";
    }

    @GetMapping("hi")
    public String hi() {
        return "Hi World!";
    }
}

• Buka terminal pada IDE kalian masing-masing, pada VSCode bisa dengan menggunakan shortcut Ctrl + ~. Atau bisa juga kita menggunakan CMD atau command prompt apabila fellowdevs lebih terbiasa di Windows.

• Pastikan lokasi folder di terminal saat ini adalah di dalam project kita.

• Run command mvn clean spring-boot:run

• Berdoa agar tidak error 😂

Setting up Database

psql -U postgres

CREATE DATABASE bcaitworks;

• id adalah kolom identifier untuk setiap record. Nantinya kita akan isi dengan UUID.

• Kolom title akan menampung judul dari task.

• is_done akan menampung status dari task.

• Empat kolom lain yaitu created_by, modified_by, created_date dan modified_date adalah kolom audit trail. Saya sangat merekomendasikan untuk selalu menambahkan kolom audit trail semacam ini dalam setiap tabel terutama tabel yang ditujukan untuk menyimpan data transaksi aplikasi. Audit trail fields ini akan membantu kita nantinya terutama dalam hal data integrity.

package com.bca.adam.model;

import java.util.Calendar;
import java.util.Date;
import java.util.UUID;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Table;

import org.hibernate.annotations.ColumnDefault;
import org.hibernate.annotations.GenericGenerator;
import org.hibernate.annotations.Type;

import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.ToString;

@Entity
@Table(name = "todo")
@Data
@ToString
@EqualsAndHashCode
public class Todo {

    @Id
    @GeneratedValue(generator = "UUID")
    @Type(type = "pg-uuid")
    @GenericGenerator(name = "UUID", strategy = "org.hibernate.id.UUIDGenerator")
    @Column(name = "id", updatable = false, nullable = false)
    private UUID id;

    @Column(name = "title")
    private String title;

    @Column(name = "created_date")
    @ColumnDefault("NOW()")
    private Date createdDate;

    @Column(name = "modified_date")
    private Date modifiedDate;

    @Column(name = "is_done")
    private boolean isDone;

    public Todo(String title) {
        this.title = title;
        this.createdDate = Calendar.getInstance().getTime();
    }
}

• @Entity adalah anotasi untuk memberi tahu Spring bahwa class ini adalah sebuah entity object. Dalam JPA, entity adalah wajib.

• @Table menerangkan bahwa class ini adalah representasi dengan tabel di database dengan nama todo.

• @Data, @ToString, @EqualsAndHasCode adalah anotasi dari Lombok. Library ini memudahkan kita terutama dalam membuat aksesor mutator sebuah object. Selebihnya tentang Lombok dapat dipelajari di sini.

• @Id adalah anotasi untuk menunjukan ID atau dapat juga dianalogikan sebagai primary key (PK) pada entity. Entity wajib memiliki ID.

• Karena ID ini akan kita generate dengan format UUID, maka kita perlu men-define generatornya. Dalam hal ini, kita anotasikan dengan @GeneratedValue, @Type serta @GenericGenerator seperti pada code di atas.

• Sama halnya seperti @Table, @Column mendefinisikan bahwa field Java object ini akan menjadi field / kolom pada tabel di database.

• @ColumnDefault digunakan untuk mendefinisikan default value suatu kolom.

spring.datasource.url= jdbc:postgresql://localhost:5432/bcaitworks
spring.datasource.username= postgres
spring.datasource.password= admin

spring.jpa.properties.hibernate.dialect= org.hibernate.dialect.PostgreSQLDialect

# Hibernate ddl auto (create, create-drop, validate, update)
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

• Yang pertama kita perlu definisikan URL database kita dalam ekspresi datasource. Karena kita bekerja di localhost dan default port PostgreSQL adalah 5432, maka koneksi host kita adalah localhost:5432/{database_name}. {database_name} diganti dengan nama database masing-masing.

• Kemudian, kita juga definisikan credentials untuk koneksi database tersebut.

• Karena banyak varian database yang ada dan library Spring JPA dibuat se-generic mungkin, maka kita perlu secara spesifik mendefinisikan jenis database yang kita pakai. Hal ini akan berpengaruh pada dialect / query generation yang digunakan saat melakukan operasi ke database kita sesuai dengan varian yang digunakan. Dalam hal ini kita gunakan dialect dari PostgreSQL.

• Nah untuk memanfaatkan fitur auto generation object database melalui aplikasi kita, kita perlu menambahkan property spring.jpa.hibernate.ddl-auto. Property ini memberi tahu Spring bahwa kita ingin Spring JPA untuk membuatkan object database secara otomatis saat aplikasi up pertama kali. Untuk valuenya, kita isi dengan update saja.

• spring.jpa.show-sql adalah opsi apabila kita ingin menampilkan query yang di-generate oleh JPA saat aplikasi dijalankan. Karena ini akan berpengaruh pada logging system aplikasi dan sangat verbose, aktifkan hanya untuk dev purpose saja.

postgres=# \c bcaitworks
You are now connected to database "bcaitworks" as user "postgres".
bcaitworks=# \d
        List of relations
 Schema | Name | Type  |  Owner
--------+------+-------+----------
 public | todo | table | postgres
(1 row)


bcaitworks=# \d todo
                             Table "public.todo"
    Column     |            Type             | Collation | Nullable | Default
---------------+-----------------------------+-----------+----------+---------
 id            | uuid                        |           | not null |
 created_date  | timestamp without time zone |           |          | now()
 is_done       | boolean                     |           | not null | false
 modified_date | timestamp without time zone |           |          |
 title         | character varying(255)      |           | not null |
 created_by    | character varying(255)      |           |          |
 modified_by   | character varying(255)      |           |          |
Indexes:
    "todo_pkey" PRIMARY KEY, btree (id)

Project's APIs development

.
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com/bca/adam
│   │   │       ├── model
│   │   │       ├── repository
│   │   │       ├── controller
│   │   │       └── service
│   │   └── resources

package com.bca.adam.repository;

import java.util.List;
import java.util.Optional;
import java.util.UUID;

import com.bca.adam.model.Todo;

import org.springframework.data.jpa.repository.JpaRepository;

public interface TodoRepository extends JpaRepository<Todo, String> {
    //get todo by ID
    Optional<Todo> findById(UUID id);

    //get all todo, similar with "SELECT * FROM todo;"
    //this actually included in JpaRepository
    //it is written here just to avoid confusion for beginners
    List<Todo> findAll();
}

package com.bca.adam.service;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.Optional;
import java.util.UUID;

import com.bca.adam.model.Todo;
import com.bca.adam.repository.TodoRepository;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import lombok.extern.slf4j.Slf4j;

@Service
@Slf4j
public class TodoService {

    @Autowired
    TodoRepository todoRepo;

    public List<Todo> getAll() {
        List<Todo> todos = new ArrayList<>();
        todoRepo.findAll().forEach(todos::add);

        if (todos.isEmpty()) {
            log.info("You have no todos!");
            return new ArrayList<>();
        }

        return todos;
    }
}

• @Service adalah anotasi untuk memberi tahu Spring bahwa class ini adalah sebuah component penting, yaitu Service.

• @Slf4j kita tambahkan untuk menambahkan fungsi logging pada aplikasi kita secara otomatis dan mudah. Anotasi ini kita dapatkan dari library Lombok yang kita tambahkan pada pom.xml. Bayangkan kalau kita tidak menggunakan Lombok, akan lebih banyak lagi memakan waktu dan langkah untuk sekedar membuat fungsi logging.

• @Autowired adalah anotasi yang sangat penting dalam Spring. Salah satu keunggulan Spring adalah IoC (Inversion of Control) atau sering juga disebut Dependency Injection (DI). Anotasi @Autowired memungkinkan kita dengan mudah untuk melakukannya.

• Sisa code lainnya adalah OOP biasa, yaitu memanggil fungsi dari TodoRepository, melakukan validasi kosong/tidak, kemudian mengembalikannya sebagai return value fungsi getAll().

package com.bca.adam.controller;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.bca.adam.model.Todo;
import com.bca.adam.service.TodoService;

import io.swagger.annotations.Api;
import lombok.extern.slf4j.Slf4j;

@CrossOrigin(origins = "*")
@RestController
@RequestMapping("/todo")
@Slf4j
public class TodoController {

    @Autowired
    TodoService todoService;

    @GetMapping("")
    public ResponseEntity<List<Todo>> getAll() {
        log.info("Getting todo list...")
        try {
            List<Todo> todos = todoService.getAll();
            if (todos.isEmpty()) {
                return new ResponseEntity<>(HttpStatus.NO_CONTENT);
            }
            return new ResponseEntity<>(todos, HttpStatus.OK);
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }
}

• Request menuju ke TodoController kita arahkan menggunakan path /todo melalui anotasi @RequestMapping("/todo")

• @CrossOrigin ditambahkan untuk mencegah error CORS.

INFO 12240 --- [nio-8080-exec-3] com.bca.adam.service.TodoService         : You have no todos!

INSERT INTO public.todo (id,title) VALUES ('e8e40842-eb4d-4d0c-8d55-f5124c3051fa'::uuid,'Cuci baju');

[
    {
        "id": "e8e40842-eb4d-4d0c-8d55-f5124c3051fa",
        "title": "Cuci baju",
        "createdDate": "2023-02-10T10:00:21.527+00:00",
        "modifiedDate": null,
        "done": false
    }
]

// .... previous lines
    public Todo addTodo(Todo todo) {
        return todoRepo.save(new Todo(todo.getTitle()));
    }

• Fungsi addTodo akan menerima parameter berupa object class Todo. Karena object ini sudah serupa dengan generic type yang kita tentukan saat mengimplementasikan JPA yakni JpaRepository<Todo, String>, maka Spring akan dengan mudah memproses object ini untuk di-map ke dalam entity.

• Fungsi save yang dipanggil melalui todoRepo adalah bawaan dari JpaRepository.

• Untuk tahap ini, kita hanya akan mengambil field title saja dari parameter yang diterima. Oleh karena itu saya membuat new object dengan menggunakan constructor yang sudah saya definisikan pada class Todo sebelumnya.

// ... previous lines
    /*
     * basically you might want to use DTO object to store the request and response
     * payload instead of the model itself
     */
    @PostMapping("")
    public ResponseEntity<Todo> addTodo(@RequestBody Todo todo) {
        try {
            if (todo.getTitle() == null || !StringUtils.hasText(todo.getTitle())) {
                log.info("To add item to your todo list, you must give it a title!");
                return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
            }
            return new ResponseEntity<>(todoService.addTodo(todo), HttpStatus.OK);
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }

{
    "title": "Kerjain tugas BCAITWORKS!",
    "unmapped_field": "i'm not gonna be mapped!"
}

// returned todo list after adding data
[
    {
        "id": "e8e40842-eb4d-4d0c-8d55-f5124c3051fa",
        "title": "Cuci baju",
        "createdDate": "2023-02-10T10:00:21.527+00:00",
        "modifiedDate": null,
        "done": false
    },
    {
        "id": "ab7ec7ce-e159-4e53-8647-edb555281876",
        "title": "Kerjain tugas BCAITWORKS!",
        "createdDate": "2023-02-11T18:39:22.598+00:00",
        "modifiedDate": null,
        "done": false
    }
]

// ... previous lines
    public Todo modifyTodo(String id) {
        Optional<Todo> todo = todoRepo.findById(UUID.fromString(id));
        if (todo.isPresent()) {
            Todo existTodo = todo.get();
            existTodo.setDone(!existTodo.isDone());
            existTodo.setModifiedDate(new Date());
            return todoRepo.save(existTodo);
        } else {
            throw new IllegalArgumentException(String.format("data with id %s not found.", id));
        }
    }

// ... previous lines
    @PutMapping("")
    public ResponseEntity<Todo> modifyTodo(@RequestBody Map<String, String> body) {
        try {
            if (body.get("id") == null)
                return new ResponseEntity<>(HttpStatus.BAD_REQUEST);

            return new ResponseEntity<>(todoService.modifyTodo(body.get("id")), HttpStatus.OK);
        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
        }
    }

    {
        "id": "ab7ec7ce-e159-4e53-8647-edb555281876",
        "title": "Kerjain tugas BCAITWORKS!",
        "createdDate": "2023-02-11T18:39:22.598+00:00",
        "modifiedDate": null,
        "done": false
    }

{
    "id": "ab7ec7ce-e159-4e53-8647-edb555281876",
    "title": "Kerjain tugas BCAITWORKS!",
    "createdDate": "2023-02-11T18:39:22.598+00:00",
    "modifiedDate": "2023-02-12T06:24:00.989+00:00",
    "done": true // this switches to false and true everytime the call happen according to current status
}

What's Next?

🎁 Bonus!