Mission: Relational Database Backend

Mission: Relational Database Backend

Table of Contents

• Description
• User Problem
• Concepts & Architectural Patterns
• Use Case
  • Prerequisites
  • Performing the Use Case
  • Details / Hints About Implementations
• Acceptance Criteria
  • Vert.x-specific Acceptance Criteria
  • Swarm-specific Acceptance Criteria
  • SpringBoot-specific Acceptance Criteria
• Approval

ID	Short Name
101	crud

Description

This experience showcases simple database interaction in a Cloud environment. The example application exposes an HTTP API, which provides “CRUD” endpoints to manipulate data through Create, Read, Update, and Delete operations. The API consumes and provides JSON documents which contain information about the request to be processed and the response returned from the system.

User Problem

User would like to implement a relational (or SQL) database API connection with endpoints exposed over HTTP.

Concepts & Architectural Patterns

• HTTP API

• CRUD

• Database

• RDBMS

• SQL database

Use Case

The purpose of this experience is to demonstrate how a developer can quickly implement a CRUD application using the Obsidian platform. The application is using a database to store the managed items. The API has been designed to be simple and intuitive. Additionally, this experience demonstrates how an application can locate and use a relational database.

The experience is built upon an application to manage fruits. The user experience is delivered using a web page proposing the CRUD operations (create / retrieve / update and delete). The user can also use the service endpoint directly.

While this experience does not showcase a fully matured RESTful model (level 3), it uses HTTP verbs and status.

Prerequisites

• The user has accessed to an OpenShift instance, and is logged in (using oc login …)

• The user has selected a project in which the application is going to be deployed. This project has been given the following permissions

  $ oc policy add-role-to-user admin ${USERNAME} -n $PROJECT_NAME
  $ oc policy add-role-to-user view -n ${NAME} -z default

• The user’s project has a PostGreSQL database installed (and running). The user has been given the credential (as OpenShift secrets). As example, creating the database can be done as follows:

  oc new-app \
   -p POSTGRESQL_USER=luke \
   -p POSTGRESQL_PASSWORD=secret \
   -p POSTGRESQL_DATABASE=my_data \
   -p DATABASE_SERVICE_NAME=my-database \
   --name=my-database \
   --template=postgresql-ephemeral
     Deploying secret can be done as follows:
  oc create -f credentials-secret.yml

Performing the Use Case

1. The user deploys the application using the deployment instructions.

   mvn fabric8:deploy -Popenshift

2. The user can access the application using a web page provided by the application

Details / Hints About Implementations

• Each runtime decides how the database interactions are implemented. One can use JDBC while others can use JPA or an ORM. Each runtime decides what would be the best way.

• Each runtime decides how the schema is going to be created.

Acceptance Criteria

The API manages a set of “fruits”. A “fruit” has at least a name (“apple”) and an id (“1”). It may also contain other attributes. The used database is a PostGreSQL database exposed under the “my-database” service. The database name should be “my_data”.

Table 1. Black box integration test showing requests against endpoint returns responses as expected

GET /api/fruits with at least one fruit	List the fruits. Json Array containing names and ids: [{“name”: “apple”, “id”: 1}]`	200 - OK with the list
GET /api/fruits with no fruits	Empty JSON array: []	200 - OK with the empty list
POST /api/fruits	Create a new fruit. The payload is given in JSON. It must include the “name” but not the “id”	201 - OK with the fruit representation as JSON (name, id…)
POST /api/fruits - with illegal or empty payload	Does nothing - return an HTTP error	If the payload was JSON - 422 (for instance, if the id is set) If the payload was not JSON or empty 415
GET /api/fruits/:id	Returns the JSON for a single fruit: {“name”: “apple”, “id”: 1}	200 - OK with a single resource
PUT /api/fruits/:id with a valid id and payload	Edit the fruit. The name can be changed, or another attribute. The id cannot be changed	200 - OK with the updated representation
PUT /api/fruits/:id with an unknown ID	Does nothing - return an HTTP error	404 - Not found
PUT /api/fruits/:id with a valid id but illegal payload	Does nothing - return an HTTP error	If the payload was JSON - 422, for example if the name if missing. If the payload was not JSON or empty 415
DELETE /api/fruits/:id with a valid id	Delete the fruits	204 - No Content
DELETE /api/fruits/:id with an invalid id	Does nothing - return an HTTP error	404 - Not Found

All other requests on /api/* are rejected (Bad Request 400, or Not Found 404).

Optional: Response containing error (not 2xx) should also contain a JSON document:

{
    “error”: “some description for human”,
    “code”: “an optional code for robot”
}

Vert.x-specific Acceptance Criteria

Swarm-specific Acceptance Criteria

SpringBoot-specific Acceptance Criteria

Approval

Coordination Owner	Clement Escoffier	☑
PM	John Clingan	☑
Vert.x	Clement Escoffier	☑
WildFly Swarm	Heiko Braun	☑
Spring Boot	Charles Moulliard	☑
QE	Tomas Schlosser	☑
Docs	Stefan Sitani	☑
DevExp	Andrew Lee Rubinger	☑
Architect	Scott Stark	☑