项目作者: enisinanaj

项目描述 :
Spring MVC RESTful example (Company and Beneficial owners endpoints)
高级语言: Java
项目地址: git://github.com/enisinanaj/company-rest-endpoints.git
创建时间: 2018-06-16T22:54:22Z
项目社区:https://github.com/enisinanaj/company-rest-endpoints

开源协议:GNU General Public License v3.0

下载


RESTful API with Spring MVC

CircleCI codecov Heroku

This project is an example implementation of a RESTful API in Java using the Spring MVC framework.

Getting Started

Clone this project and run the application with gradle, using gradle wrapper:

  1. gradlew bootRun

or your own gradle installation

  1. gradle bootRun

Prerequisites

You’ll need Java JDK 1.8+ installed. Gradle is not necessary because gradlew wrapper is provided with the project as described above.

To check for bugs and be able to browse them locally you have to download Spotbugs from http://spotbugs.readthedocs.io/en/latest/installing.html. Download it in zip format, then launch the spotbugs executable that is found inside the bin folder. Once the application is running, you can go to File > Open and select the findbugs report file (.xml) generally inside ${project_root}/build/reports/spotbugs/main.xml

Available endpoints

Companies (/companies)

POST /companies to create a new company

  1. ## Create a new company
  2. curl -X "POST" "http://localhost:8080/companies" \
  3. -H 'Content-Type: application/json' \
  4. -d $'{
  5. "email": "info@apple.com",
  6. "phone": "+1 333 555 8294",
  7. "country": "USA",
  8. "name": "Apple, INC",
  9. "city": "Coupertino",
  10. "address": "One Infinite Loop"
  11. }'

the expected HTTP result is as follows

  1. HTTP/1.1 201
  2. Location: http://localhost:8080/companies/17
  3. Content-Length: 0
  4. Date: Sun, 17 Jun 2018 00:46:52 GMT
  5. Connection: close

returning a Location header that points at the newly created resource.

GET /companies to obtain a list of all companies present in the database

  1. ## Get all companies
  2. curl "http://localhost:8080/companies"

returns a json array of companies

  1. HTTP/1.1 200
  2. Content-Type: application/json;charset=UTF-8
  3. Transfer-Encoding: chunked
  4. Date: Sun, 17 Jun 2018 00:52:01 GMT
  5. Connection: close
  6. [
  7. {
  8. "id": 17,
  9. "name": "Apple, INC",
  10. "address": "One Infinite Loop",
  11. "city": "Coupertino",
  12. "country": "USA",
  13. "email": "info@apple.com",
  14. "phone": "+1 333 555 8294",
  15. "beneficialOwners": []
  16. }
  17. ]

GET /companies/{companyId} to obtain the information regarding a single company. Example GET /companies/17 as below

  1. ## Getting all data of company 17
  2. curl "http://localhost:8080/companies/17"

Result:

  1. HTTP/1.1 200
  2. Content-Type: application/json;charset=UTF-8
  3. Transfer-Encoding: chunked
  4. Date: Sun, 17 Jun 2018 00:56:13 GMT
  5. Connection: close
  6. {
  7. "id": 17,
  8. "name": "Apple, INC",
  9. "address": "One Infinite Loop",
  10. "city": "Coupertino",
  11. "country": "USA",
  12. "email": "info@apple.com",
  13. "phone": "+1 333 555 8294",
  14. "beneficialOwners": []
  15. }

Note that if the given company ID does not exist an HTTP NotFound error will be returned with a 404 status code.

PATCH /companies/{companyId} can be used to update one or more fields of the company resource.

Curl call example:

  1. ## Update company fields
  2. curl -X "PATCH" "http://localhost:8080/companies/1" \
  3. -H 'Content-Type: application/json' \
  4. -d $'{
  5. "email": "info@one.com",
  6. "phone": "+1 333 555 8294",
  7. "country": "USA",
  8. "name": "One",
  9. "city": "Loop",
  10. "address": "Infinite"
  11. }'

Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json;charset=UTF-8
  3. Transfer-Encoding: chunked
  4. Date: Sun, 17 Jun 2018 01:40:08 GMT
  5. Connection: close
  6. {
  7. "id": 1,
  8. "name": "One",
  9. "address": "Infinite",
  10. "city": "Loop",
  11. "country": "USA",
  12. "email": "info@one.com",
  13. "phone": "+1 333 555 8294",
  14. "beneficialOwners": [
  15. {
  16. "id": 2,
  17. "name": "jhoeller"
  18. }
  19. ]
  20. }

Note that if the given company ID does not exist an HTTP NotFound error will be returned with a 404 status code.

Beneficial owners of a company (/companies/{companyId}/beneficialOwners)

The provided methods for these resources are GET allo beneficial owners of a company and POST (create) a new beneficial owner.

POST /companies/{companyId}/beneficialOwners to create a new Beneficial owner

  1. ## Create a new beneficial owner for the given company resource
  2. curl -X "POST" "http://localhost:8080/companies/17/beneficialOwners" \
  3. -H 'Content-Type: application/json' \
  4. -d $'{
  5. "name": "Beneficial"
  6. }'

Response from this call is as follows:

  1. HTTP/1.1 201
  2. Location: http://localhost:8080/companies/17/beneficialOwners/18
  3. Content-Length: 0
  4. Date: Sun, 17 Jun 2018 22:15:40 GMT
  5. Connection: close

GET /companies/{companyId}/beneficialOwners to obtain all beneficial owners of the given company

  1. ## Create a new company
  2. curl "http://localhost:8080/companies/17/beneficialOwners" \
  3. -H 'Content-Type: application/json'

Responds with the following array of object

  1. HTTP/1.1 200
  2. Content-Type: application/json;charset=UTF-8
  3. Transfer-Encoding: chunked
  4. Date: Sun, 17 Jun 2018 22:22:12 GMT
  5. Connection: close
  6. [{"id":18,"name":"Beneficial"}]

Note that if the given company ID does not exist an HTTP NotFound error will be returned with a 404 status code.

Running the tests

The tests are run easily with the gradle task

  1. gradlew test

For a better reporting there is another gradle task available which runs the tests and aferwards ccreates the reports in jacoco xml format. This task also runs spotbugs. To have a browsable report from Jacoco you need to edit the build file build.gradle from this

  1. jacocoTestReport {
  2. reports {
  3. xml.enabled true
  4. csv.enabled false
  5. html.enabled = false
  6. //html.destination file("${buildDir}/jacocoHtml")
  7. }
  8. }

to this

  1. jacocoTestReport {
  2. reports {
  3. xml.enabled false
  4. csv.enabled false
  5. html.enabled = true
  6. }
  7. }

To have tests run and reports generated, execute the following gradle task:

  1. gradlew check

Deployment

Application is deployed to Heroku at https://restful-cmp.herokuapp.com/companies

Authentication

A suggested authentication method between client and this backend server would be two-legged OAuth 2.0.

As described in this image
2-legged OAuth 2.0

Built With

Authors

  • Eni Sinanaj - Initial work

License

This project is licensed under the GPL 3.0 - see the LICENSE.md file for details