Showing posts with label rest-api. Show all posts

Spring boot rest api with Mongodb CRUD examples

In previous articles we have seen Creating first rest api in spring-boot and also Passing and validating RequestParam in spring-boot rest api now we will take one step further by interacting with database. Also checkout Spring boot rest api with MySQL CRUD examples or browse all spring tutorials here.

build.gradle
update your build.gradle, add following dependencies and refresh the project, gradle will download the required dependencies(jar files).
//mongodb dependencies
compile('org.springframework.boot:spring-boot-starter-data-mongodb')
application.properties
Create new source folder under src/main/resources if not exist and add new file called application.properties. Add following lines for database connection.
#mongodb
spring.data.mongodb.host=127.0.0.1
spring.data.mongodb.port=27017
spring.data.mongodb.database=spring_boot_examples
spring.data.mongodb.username=root
spring.data.mongodb.password=root

Source code (User.java)
Note: In current example we are using spring boot 1.5.7.RELEASE which uses validations framework 1.1.0. @NotEmpty, @Email are part of package org.hibernate.validator. But spring boot 2.0.0 and above which supports validation framework 2.0 so @NotEmpty, @Email, etc... are now part of javax.validation.constraints.
import java.util.Date;
import javax.validation.constraints.Size;
import org.hibernate.validator.constraints.NotEmpty;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;
import org.springframework.data.mongodb.core.mapping.Field;

/**
 * @author javaQuery
 * @since 2018-09-24
 * @github https://github.com/javaquery/spring-boot-examples
 */
@Document(collection = "users")
public class User{

    @Id
    public String id;

    @Field("first_name")
    @NotEmpty(message = "first_name can not be empty.")
    @Size(max = 100, message = "first_name can not be more than 100 characters.")
    private String firstName;
 
    @Field("last_name")
    @NotEmpty(message = "last_name can not be empty.")
    @Size(max = 100, message = "last_name can not be more than 100 characters.")
    private String lastName;
 
    @Field("email")
    @NotEmpty(message = "email can not be empty.")
    @Size(max = 100, message = "email can not be more than 100 characters.")
    private String email;
 
    @Field("password")
    @NotEmpty(message = "password can not be empty.")
    @Size(max = 100, message = "password can not be more than 100 characters.")
    private String password;
 
    @Field("created")
    private Long created = (new Date().getTime())/ 1000;
 
    @Field("modified")
    private Long modified  = (new Date().getTime())/ 1000;

    //getter-setter
}

Abstraction in Spring
Spring is all about abstraction via interfaces. Abstraction allows you to change the implementation without affecting caller method.

Repositories
The goal of Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.
Spring Repository(interface) is abstraction for data access layer.

For example in your project you are going to use data storage like MySQL(RDBMS), MongoDb (NoSQL), etc... The caller class will interact to data storage using repository(interface) so for caller class it doesn't matter which storage you are using in implementation of repository either MySQL or MongoDb as long as data persist and retrieve back.

Here we are using MongoRepository for which spring will provide default implementation of MongoDb queries (INSERT, UPDATE, DELETE, SELECT) without writing it yourself.

Source code (MongoRepository.java)
import java.util.UUID;
import org.springframework.data.mongodb.repository.MongoRepository;
import com.javaquery.examples.springboot.model.mongodb.User;

/**
 * @author javaQuery
 * @since 2018-09-24
 * @github https://github.com/javaquery/spring-boot-examples
 */
public interface UserMongoDbRepository extends MongoRepository<User, String>{
}
Now if you want to save record (User), all you got to do is call userMongoDbRepository.save(user);. Calling save on UserRepository will generate INSERT statement and execute it. Similarly you can perform update, select and delete.

Source code (Application.java)
Add @EnableMongoRepositories in your Application.java.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.data.mongodb.repository.config.EnableMongoRepositories;

/**
 * @author javaQuery
 * @since 2018-01-31
 * @github https://github.com/javaquery/spring-boot-examples
 */
@SpringBootApplication
@ComponentScan(basePackages = { "com.javaquery.examples.springboot.rest" })
@EnableMongoRepositories("com.javaquery.examples.springboot.model.mongodb.repositories")
public class Application {
    public static void main(String[] args) {
       SpringApplication.run(Application.class, args);
    }
}
  • @EnableMongoRepositories - Location(package) of your code which interact with database (repositories)

Services
Service is abstraction layer for application logic implementation.

Source code (UserMongoDbService.java)
UserMongoDbDTO / UserMongoDbDTO are request objects (JSON Payload). Source code is available under controller section.
import com.javaquery.examples.springboot.rest.dto.UserMongoDbDTO;
import com.javaquery.examples.springboot.rest.dto.UserUpdateDTO;

/**
 * @author javaQuery
 * @since 2018-09-24
 * @github https://github.com/javaquery/spring-boot-examples
 */
public interface UserMongoDbService {
    public UserMongoDbDTO addUser(UserMongoDbDTO userDTO);
    public UserMongoDbDTO getUser(String id);
    public UserMongoDbDTO updateUser(UserUpdateDTO userUpdateDTO, String id);
    public void deleteUser(String id);
}
Source code (UserMongoDbServiceImpl.java)
import java.util.Objects;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.javaquery.examples.springboot.model.mongodb.User;
import com.javaquery.examples.springboot.model.mongodb.repositories.UserMongoDbRepository;
import com.javaquery.examples.springboot.rest.dto.UserMongoDbDTO;
import com.javaquery.examples.springboot.rest.dto.UserUpdateDTO;
import com.javaquery.examples.springboot.rest.exception.EntityNotFoundException;
import com.javaquery.examples.springboot.rest.service.UserMongoDbService;

/**
 * @author javaQuery
 * @since 2018-09-24
 * @github https://github.com/javaquery/spring-boot-examples
 */
@Service
public class UserMongoDbServiceImpl implements UserMongoDbService {

    @Autowired
    private UserMongoDbRepository userMongoDbRepository;

    @Override
    public UserMongoDbDTO addUser(UserMongoDbDTO userDTO) {
        /**
         * We are manually creating {@link User} object however there is mapper
         * available to convert to-from {@link UserDTO}.
         */
        User user = new User();
        user.setFirstName(userDTO.getFirstName());
        user.setLastName(userDTO.getLastName());
        user.setEmail(userDTO.getEmail());
        user.setPassword(userDTO.getPassword());
        userMongoDbRepository.save(user);

        /* set generated user id to response object */
        userDTO.setId(user.getId());
        userDTO.setPassword("");
        return userDTO;
    }

    @Override
    public UserMongoDbDTO getUser(String id) {
        User user = userMongoDbRepository.findOne(id);
        if (Objects.isNull(user)) {
            /* handle this exception using {@link RestExceptionHandler} */
            throw new EntityNotFoundException(User.class, id);
        }
        return new UserMongoDbDTO().build(user);
    }

    @Override
    public UserMongoDbDTO updateUser(UserUpdateDTO userUpdateDTO, String id) {
        User user = userMongoDbRepository.findOne(id);
        if (Objects.isNull(user)) {
            /* handle this exception using {@link RestExceptionHandler} */
            throw new EntityNotFoundException(User.class, id);
        }
        user.setFirstName(userUpdateDTO.getFirstName());
        user.setLastName(userUpdateDTO.getLastName());
        userMongoDbRepository.save(user);
        return new UserMongoDbDTO().build(user);
    }

    @Override
    public void deleteUser(String id) {
        userMongoDbRepository.delete(id);
    }
}

Controller (REST)
Controller is the entry point for all REST request.

Source code (UserMongoDbDTO.java)
import javax.validation.constraints.Size;
import org.hibernate.validator.constraints.Email;
import org.hibernate.validator.constraints.NotEmpty;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonInclude.Include;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.javaquery.examples.springboot.model.mongodb.User;

/**
 * Object to interact using rest api.
 *
 * @author javaQuery
 * @since 2018-09-24
 * @github https://github.com/javaquery/spring-boot-examples
 */
@JsonIgnoreProperties(ignoreUnknown = true)
@JsonInclude(Include.NON_NULL)
public class UserMongoDbDTO {

    /* used to send database id */
    private String id;

    @NotEmpty(message = "first_name can not be empty")
    @JsonProperty("first_name")
    private String firstName;

    @NotEmpty(message = "last_name can not be empty")
    @JsonProperty("last_name")
    private String lastName;

    @Email
    @JsonProperty("email")
    private String email;

    @NotEmpty(message = "password can not be empty")
    @Size(min = 6, message = "password must be at least 6 character")
    @JsonProperty("password")
    private String password;

    // getter - setter

    /**
     * We are manually creating {@link UserMongoDbDTO} object however there is
     * mapper available to convert to-from {@link User}.
     *
     * @param user
     * @return
     */
    public UserMongoDbDTO build(User user) {
        this.id = user.getId();
        this.firstName = user.getFirstName();
        this.lastName = user.getLastName();
        this.email = user.getEmail();
        return this;
    }
}

Source code (UserUpdateDTO.java)
import org.hibernate.validator.constraints.NotEmpty;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
 * Object to interact using rest api.
 * @author javaQuery
 * @since 2018-02-18
 * @github https://github.com/javaquery/spring-boot-examples
 */
public class UserUpdateDTO {
    @NotEmpty(message = "first_name can not be empty")
    @JsonProperty("first_name")
    private String firstName;
 
    @NotEmpty(message = "last_name can not be empty")
    @JsonProperty("last_name")
    private String lastName;
 
    // getter - setter
}

Source code (UserMongoDbController.java)
Http request POST, GET, PUT and POST are implemented in controller.
import javax.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.javaquery.examples.springboot.rest.dto.UserMongoDbDTO;
import com.javaquery.examples.springboot.rest.dto.UserUpdateDTO;
import com.javaquery.examples.springboot.rest.response.SuccessResponse;
import com.javaquery.examples.springboot.rest.service.UserMongoDbService;

/**
 * @author javaQuery
 * @since 2018-09-24
 * @github https://github.com/javaquery/spring-boot-examples
 */
@RestController
@RequestMapping("/api/user/mongodb")
public class UserMongoDbController {

    @Autowired
    private UserMongoDbService userMongoDbService;

    @PostMapping
    public ResponseEntity<UserMongoDbDTO> addUser(@Valid @RequestBody UserMongoDbDTO userDTO) {
        return ResponseEntity.ok(userMongoDbService.addUser(userDTO));
    }

    @GetMapping
    public ResponseEntity<UserMongoDbDTO> getUser(@RequestParam String id) {
        return ResponseEntity.ok(userMongoDbService.getUser(id));
    }

    @PutMapping
    public ResponseEntity<UserMongoDbDTO> updateUser(@Valid @RequestBody UserUpdateDTO userUpdateDTO, @RequestParam String id) {
        return ResponseEntity.ok(userMongoDbService.updateUser(userUpdateDTO, id));
    }

    @DeleteMapping
    public ResponseEntity<?> deleteUser(@RequestParam String id) {
        userMongoDbService.deleteUser(id);
        return ResponseEntity.ok(new SuccessResponse("deleted"));
    }
}
Note: Add updated EntityNotFoundException.java and RestExceptionHandler.java from github.

Request/Response
cURL POST http://localhost:8080/api/user/mongodb
-body {"first_name":"vicky","last_name":"thakor","email":"vicky.thakor@javaquery.com","password":"123456"}
-code 200
-body {"id":"5bada32eac0eb2127413b580","first_name":"vicky","last_name":"thakor","email":"vicky.thakor@javaquery.com","password":""}
cURL GET http://localhost:8080/api/user/mongodb?id=5bada32eac0eb2127413b580
-code 200
-body {"id":"5bada32eac0eb2127413b580","first_name":"vicky","last_name":"thakor","email":"vicky.thakor@javaquery.com"}
cURL PUT http://localhost:8080/api/user/mongodb?id=5bada32eac0eb2127413b580
-body {"first_name":"vickey","last_name":"thakor"}
-code 200
-body {"id":"5bada32eac0eb2127413b580","first_name":"vickey","last_name":"thakor","email":"vicky.thakor@javaquery.com"}
cURL DELETE http://localhost:8080/api/user/mongodb?id=5bada32eac0eb2127413b580
-code 200
-body {"message": "deleted"}

Spring internationalization(i18n) example for response and errors

Nowadays,  your application has users from around the world. For ease of your user, you want them to use web application in their local language. You must consider internationalization (i18n) while creating your web application.

In following example we will learn how you can apply internationalization to your spring application. In my previous articles we learned Creating first rest api in spring-boot and you can browse all spring article for starter.

Language specific properties file
Create properties file under src/main/resource folder for individual language you want to support in your application. We create package locale under folder and placed all file in it.

messages_de.properties
springboot.hello=Hallo
springboot.customerror=benutzerdefinierte Fehlermeldung
messages_en.properties
springboot.hello=Hello
springboot.customerror=custom error message
messages_fr.properties
springboot.hello=Bonjour
springboot.customerror=message d'erreur personnalisé
messages_zh.properties
For Chinese character you have to convert character / word into Unicode. How to convert Chinese character or word to Unicode online?
springboot.hello=\u4f60\u597d
springboot.customerror=\u81ea\u5b9a\u4e49\u9519\u8bef\u6d88\u606f

Source code (ApplicationConfig.java)
Load your language properties file in spring context using ReloadableResourceBundleMessageSource.
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ReloadableResourceBundleMessageSource;
import org.springframework.validation.Validator;
import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

/**
 * @author javaQuery
 * @since 2018-02-18
 * @github https://github.com/javaquery/spring-boot-examples
 */
@Configuration
public class ApplicationConfig extends WebMvcConfigurerAdapter{
    @Bean
    public ReloadableResourceBundleMessageSource messageSource(){
        ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
        messageSource.setBasename("classpath:locale/messages");
        messageSource.setDefaultEncoding("UTF-8");
        return messageSource;
    }
 
    /**
     * Internationalization for parameter and payload validation messages. 
     * @return
     */
    @Bean
    public LocalValidatorFactoryBean validator() {
       LocalValidatorFactoryBean bean = new LocalValidatorFactoryBean();
       bean.setValidationMessageSource(messageSource());
       return bean;
    }

    @Override
    public Validator getValidator() {
       return validator();
    }
}

Source code (Application.java)
Add ApplicationConfig.java file package com.javaquery.examples.springboot.main.config in Application.java for component scan.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;

/**
 * @author javaQuery
 * @since 2018-01-31
 * @github https://github.com/javaquery/spring-boot-examples
 * 
 * @change message internationalization (locale)
 */
@SpringBootApplication
@ComponentScan(basePackages = { "com.javaquery.examples.springboot.rest",  "com.javaquery.examples.springboot.main.config"})
@EntityScan("com.javaquery.examples.springboot.model")
@EnableJpaRepositories("com.javaquery.examples.springboot.model.repositories")
public class Application {
    public static void main(String[] args) {
       SpringApplication.run(Application.class, args);
    }
}

Source code (LocaleController.java)
import java.util.Locale;
import javax.validation.constraints.Size;
import org.hibernate.validator.constraints.NotEmpty;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * Springboot internationalization example
 * @author javaQuery
 * @since 2018-04-06  
 */
@RestController
@RequestMapping("/api")
@Validated
public class LocaleController {
 
    @Autowired
    private MessageSource messageSource; 
 
    /**
     * Response internationalization.
     * @param name
     * @param locale
     * @return
     */
    @GetMapping("/locale")
    public ResponseEntity<?> sayHello(@RequestParam("name") String name, Locale locale){
       String localeHello = messageSource.getMessage("springboot.hello", null, locale);
       return ResponseEntity.ok(localeHello + " " + name);
    }
 
    /**
     * Validation parameter internationalization. 
     * @param firstname
     * @param lastname
     * @param notEmptyParam
     * @param locale
     * @return
     */
    @GetMapping("/locale/param")
    public ResponseEntity<?> parameterValidation(@Size(min = 1, max = 5, message = "firstname {javax.validation.constraints.Size.message}") @RequestParam("firstname") String firstname,
       @NotEmpty(message = "lastname {org.hibernate.validator.constraints.NotEmpty.message}") @RequestParam("lastname") String lastname,
       @NotEmpty(message = "{springboot.customerror}") String notEmptyParam, Locale locale){
         String localeHello = messageSource.getMessage("springboot.hello", null, locale);
         return ResponseEntity.ok(localeHello + " " + firstname + " " + lastname);
    }
}
We used properties file key springboot.hello to send language specific response of "Hello".

Internationalization for error messages
parameterValidation method demonstrate use of internationalization code for validation.
 - You can create your own custom code like {springboot.customerror}.
 - Use inbuilt codes. You find out internationalization code from source of annotation.


Enable Internationalization
To enable internationalization for http request send header accept-language in your request.

Request/Response
cURL POST localhost:8080/api/locale?name=vicky
-H 'accept-language: fr'
-code 200
-body Bonjour vicky
cURL POST localhost:8080/api/locale/param?firstname=VickyV&lastname=Thakor
-H 'accept-language: de'
-code 400
-body {"errors":["firstname muss zwischen 1 und 5 liegen","benutzerdefinierte Fehlermeldung"]}

Creating first rest api in spring-boot

spring-boot
Today we are going to learn how to create rest api in spring-boot. This example is created using gradle, if you are not familiar with how to setup gradle project in eclipse follow the steps stated in Setup first gradle project in eclipse

build.gradle
update your build.gradle as follow and refresh the project, gradle will download the required dependencies(jar files).
buildscript {
    ext {
        springBootVersion = '1.5.7.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'
sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    compile('org.springframework.boot:spring-boot-starter-web')
}

Source code (HelloWorldController.java)
Spring follows Model-View-Controller so we'll use widely used package structure and filenames. Now create package like com.example.package.rest.controller
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author javaQuery
 * @since 2018-01-31
 * @github https://github.com/javaquery/spring-boot-examples
 */
@RestController
@RequestMapping("/api") 
public class HelloWorldController {
 
 /**
  * This will send Hello World in response with HTTP status code 200.
  * @return
  */
 @GetMapping("/helloworld")
 public ResponseEntity sayHello(){
  /* return response */
  return ResponseEntity.ok("Hello World");
 }
}
Lets quickly understand annotations used in HelloWorldController.java

  • @RestController - To denote class will be service as rest service
  • @RequestMapping("/api") - default/root path for all apis created under HelloWorldController.java
  • @GetMapping("/helloworld") - sayHello method will serve for GET http request made for path /api/helloworld

Source code (Application.java)
Create Application.java (main-class) in package best suited your project,
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

/**
 * @author javaQuery
 * @since 2018-01-31
 * @github https://github.com/javaquery/spring-boot-examples
 */
@SpringBootApplication
@ComponentScan(basePackages = { "com.javaquery.examples.springboot.rest" })
public class Application {
 public static void main(String[] args) {
  SpringApplication.run(Application.class, args);
 }
}
Lets quickly understand annotations used in Application.java

  • @SpringBootApplication - denotes entry point of spring-boot application
  • @ComponentScan - files under given package(s) are part/component of spring application so spring will process the annotations.
Now run Application.java like any other java application with main method. It'll start local server and your rest API is ready to test. Open up localhost:8080/api/helloworld in your browser.

Project Structure

Source code is also available on my github repository: https://github.com/javaquery/spring-boot-examples. You can also check spring tutorials on http://www.javaquery.com/p/spring-tutorials.html and new you can do Passing and validating RequestParam in spring-boot rest api