Heybeach is a service that allows users to upload and download beach photos. In its minimum viable product (MVP), the service doesn't check the photos content therefore all kinds of photos can be uploaded. But in future releases, the service will analyze the uploaded photos and make sure the the photo contains a beach. The service is written in Java and it exposes a REST API using Spring Boot technology.
The minimum viable product (MVP) is currently deployed on Cloud Foundry and can be access via the base URL: https://heybeach.cfapps.io/ The section below describes how to use the API.
The Heybeach service offers 5 API endpoints. The user registration endpoint is publicly accessible, while the remaining endpoints are restricted. Access to the upload/list/download endpoints is only available via a bearer token which is obtained after a successful login.
HTTP Method | Mapping | Parameters | Request type | Authentication | Description | Example |
---|---|---|---|---|---|---|
POST | /heybeach/welcome/register | email, password, repeatedPassword | JSON | N/A | Registers a new user. email: must have a valid email format [email protected] password and repeatedPassword must be identical | curl --request POST --url https://heybeach.cfapps.io/heybeach/welcome/register --header 'content-type: application/json' --data '{"email": "[email protected]","password": "mickey","repeatedPassword": "mickey"}' |
POST | /oauth/token | username, password, grant_type | Form (URL-encoded) | Basic Authentication: username: "heybeachapiclientid", password: "Ob747dilVK" | User login. username should be set to the registered user's email, password should be set the registered user password. grant_type must be set to the value 'password' | curl --request POST --url https://heybeach.cfapps.io/oauth/token --header 'authorization: Basic aGV5YmVhY2hhcGljbGllbnRpZDpPYjc0N2RpbFZL' --header 'content-type: multipart/form-data; --form username=[email protected] --form password=mickey --form grant_type=password |
POST | /heybeach/home/upload | photo | Multipart Form | Bearer token | Uploads a photo for the authenticated user. the parameter photo is set to the photo's file. Accepted content types: image/jpeg and image/png | curl --request POST --url https://heybeach.cfapps.io/oauth/token --header 'authorization: Basicurl --request POST --url https://heybeach.cfapps.io/heybeach/home/upload --header 'authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsicmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJzYWZleS5oYWxpbUBnbWFpbC5jb20iLCJzY29wZSI6WyJyZWFkIiwid3JpdGUiXSwiZXhwIjoxNTQyNTcwMTQ3LCJhdXRob3JpdGllcyI6WyJTVEFOREFSRCJdLCJqdGkiOiI5YmE1YmY1OS03ZWM0LTRlYTItOWMwNy01YzU5ZjBlMDlhOWUiLCJjbGllbnRfaWQiOiJoZXliZWFjaGFwaWNsaWVudGlkIn0.2LDifEhVnPl53Cly9IZRuGQ-gAu_7UJ16A8Wzm4ME8o' --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' --form photo= aGV5YmVhY2hhcGljbGllbnRpZDpPYjc0N2RpbFZL' --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' --form username=[email protected] --form password=mickey --form grant_type=password |
GET | /heybeach/home/list | N/A | N/A | Bearer token | Lists all photo's metadata for the authenticated user. The response is a JSON array. Each elements contain a photo's metadata: id, name, type | curl --request GET --url https://heybeach.cfapps.io/heybeach/home/list --header 'authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsicmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJtaWNrZXkubW91c2VAZ21haWwuY29tIiwic2NvcGUiOlsicmVhZCIsIndyaXRlIl0sImV4cCI6MTU0MjYwMDc2NCwiYXV0aG9yaXRpZXMiOlsiU1RBTkRBUkQiXSwianRpIjoiNjIxYThmZjItYjEzNC00ZjdhLTg5OTItYWE5YTlmNTUzZGUzIiwiY2xpZW50X2lkIjoiaGV5YmVhY2hhcGljbGllbnRpZCJ9.B3jprHWFANn55dtdcs0ohXUwdHKyUwLOXWaJAmcYGoo' |
GET | /heybeach/home/download | id | N/A | Bearer token | Downloads one photo that was uploaded by the authenticated user identified by id (that can be fetched by a /list request) | curl --request GET --url 'https://heybeach.cfapps.io/heybeach/home/download?id=2' --header 'authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsicmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJtaWNrZXkubW91c2VAZ21haWwuY29tIiwic2NvcGUiOlsicmVhZCIsIndyaXRlIl0sImV4cCI6MTU0MjYwMDc2NCwiYXV0aG9yaXRpZXMiOlsiU1RBTkRBUkQiXSwianRpIjoiNjIxYThmZjItYjEzNC00ZjdhLTg5OTItYWE5YTlmNTUzZGUzIiwiY2xpZW50X2lkIjoiaGV5YmVhY2hhcGljbGllbnRpZCJ9.B3jprHWFANn55dtdcs0ohXUwdHKyUwLOXWaJAmcYGoo' |
- Clone the repository
- You can import the project in your preferred IDE, but it's recommended for Eclipse users to use Spring Tool Suite (STS) since with STS importing, building and running the project is fairly straightforward
- Install MySQL Locally. Heybeach is configured to use a database called heybeachdb available on a MySQL server deployed on localhost, listeing to port: 3306 and accessed with username:root and password: root. You can choose a different database technoloy and a different endpoint and/or credentials without affecting the service implementation. Just make sure you modifiy the configuration file (application.properties accordingly)
- Perform a gradle build (On STS, do a gradle refresh)
- Start the Spring boot application. The service should run under the base endpoint: localhost:8080/
Check the wiki