Hi guys her we go
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Build Status Build Status GitHub Release License

This is a simple REST service that provides some RESTful endpoints protected by OAuth 2. Adictionally we document all endpoints with Swagger and implements HATEOAS concepts. The REST service is based on the Spring REST Service OAuth - by Roy Clarkson and in another projects mine like Erudio API With Groovy, Semeru JSF Groovy Maven and Erudio Client WS Exporter. This project incorporates the new Java-based configuration support, now available in Spring Security OAuth 2.0. Please log any issues or feature requests to the Spring Security OAuth project.

Open Source Projects Used

The following Open Source projects are used in this sample app:

Architectural Style

Em português

Sobre REST

Sobre Groovy e Java na mesma aplicação

Sobre Groovy

How to get this project

You can execute following command or as you prefer download zip here and import in your favourite IDE.

git clone https://github.com/leandrocgsi/erudio-api-oauth2.git

How to restore database

You just need create an empty database in MySQL with name "erudio_api_db", check if your credentials are "root" and "root" and execute following command in pom.xml folder.

mvn flyway:migrate

Build and Run

Use Maven:

mvn clean package spring-boot:run


Test the city endpoint:

curl http://localhost:8080/api/v1/city/findAll

You receive the following JSON response, which indicates you are not authorized to access the resource:

  "error": "unauthorized",
  "error_description": "An Authentication object was not found in the SecurityContext"

In order to access the protected resource, you must first request an access token via the OAuth handshake. Request OAuth authorization:

curl -X POST -vu clientapp:123456 http://localhost:8080/oauth/token -H "Accept: application/json" -d "password=spring&username=roy&grant_type=password&scope=read%20write&client_secret=123456&client_id=clientapp"

A successful authorization results in the following JSON response:

  "access_token": "ff16372e-38a7-4e29-88c2-1fb92897f558",
  "token_type": "bearer",
  "refresh_token": "f554d386-0b0a-461b-bdb2-292831cecd57",
  "expires_in": 43199,
  "scope": "read write"

Use the access_token returned in the previous request to make the authorized request to the protected endpoint:

curl http://localhost:8080/api/v1/city/findAll -H "Authorization: Bearer ff16372e-38a7-4e29-88c2-1fb92897f558"

If the request is successful, you will see the following JSON response:

  "id": 1,
  "content": "Hello, Roy!"

After the specified time period, the access_token will expire. Use the refresh_token that was returned in the original OAuth authorization to retrieve a new access_token:

curl -X POST -vu clientapp:123456 http://localhost:8080/oauth/token -H "Accept: application/json" -d "grant_type=refresh_token&refresh_token=f554d386-0b0a-461b-bdb2-292831cecd57&client_secret=123456&client_id=clientapp"


To configure the project to run on HTTPS as shown in Building REST services with Spring, enable the https profile. You can do this by uncommenting the appropriate line in the application.properties file of this project. This will change the server port to 8443. Modify the previous requests as in the following command.

curl -X POST -k -vu clientapp:123456 https://localhost:8443/oauth/token -H "Accept: application/json" -d "password=spring&username=roy&grant_type=password&scope=read%20write&client_secret=123456&client_id=clientapp"

The -k parameter is necessary to allow connections to SSL sites without valid certificates or the self signed certificate which is created for this project.


HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture. A hypermedia-driven site provides information to navigate the site's REST interfaces dynamically by including hypermedia links with the responses. This capability differs from that of SOA-based systems and WSDL-driven interfaces. With SOA, servers and clients usually must access a fixed specification that might be staged somewhere else on the website, on another website, or perhaps distributed by email. According with Richardson maturity model HATEOAS is final level of REST. One API is really RESTful when implements this standart. As you can see our app have HATEOAS support.

curl http://localhost:8080/api/v1/city/findAll -H "Authorization: Bearer ff16372e-38a7-4e29-88c2-1fb92897f558"

As return, we have something like that:

    "insertDate": 1461812400000,
    "updatedDate": 1461812400000,
    "idUserInsert": 0,
    "idUserUpdate": null,
    "active": null,
    "idCity": 1,
    "name": "UBERLANDIA",
    "links": [
        "rel": "self",
        "href": "http://localhost:8080/api/v1/city/1"
    "insertDate": 1461812400000,
    "updatedDate": 1461812400000,
    "idUserInsert": 0,
    "idUserUpdate": null,
    "active": null,
    "idCity": 2,
    "name": "PATOS DE MINAS",
    "links": [
        "rel": "self",
        "href": "http://localhost:8080/api/v1/city/2"

Swagger API documentation

Swagger is a simple but powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. In January 1st 2016 the Swagger Specification has been donated to the Open API Initiative (OAI) and has been renamed to the OpenAPI Specification. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. In this example you can see the documentation API in localhost adress:


As you can see Swagger provide a simple way to document US API's.

Example Page

How to import this project

Now we just see how to import this project in Eclipse. Go to menu File >> Import >> Maven >> Existing Maven Projects >> Next.


As on image bellow type your Root Directory (where we found your code) and click in Browse >> Finish.


Probably you see the following errors, dont be worry just click in Finish again.


Now we dont see our Groovy code this is because these code is out of default Maven lifecycle. To fix this we just need click with right button over our project and select New >> Source Folder.


In next window in Folder Name type src/main/groovy, repeat this proccess with src/test/groovy and src/test_components/java


Now we have one structure similar to image bellow. As you can see, on Markers tab, we have some erros but dont be worry just click with right button and delete they.


Erudio RESTful API Archetype

Based on this project we build a Maven Archetype that can give you power to create a simple REST API in minutes. To access this Archetype and build your API based in this project pease access Erudio RESTful API Archetype and folow the steps.