Overview

ManagePeople service provides create, read, update and delete (CRUD) capabilities to a client application. In particular, it allows a client app to perform the following operations:

• List all people (GET)
• Look up a person by e-mail (GET)
• Add a new person (POST)
• Update existing person (PUT)
• Remove person (DELETE)

The service is implemented in Java using the Spring framework. You can download the code from this Github location: ManagePeople. The following is the service class diagram:

The example shown here uses JAX-RS API technology which makes even more easy to create REST services using the Java platform.

It is a great responsibility documenting all these APIs so other developers can quickly understand how to use them. It would be great to generate complete and easy to follow documentation from source code, and not to write it along the development process with all the problems involved. It sounds a pipe dream, right? But help is available in the form of Swagger

Essentially, Swagger does a simple but very powerful thing: with a bit of additional annotations it generates the REST API descriptions (HTTP methods, path / query / form parameters, responses, HTTP error codes, …) and even provides a simple web UI to play with REST calls to your APIs (not to mention that all this metadata is available over REST as well).

Access Policy

ManagePeople service runs on localhost where the client is, so no special access policy is required. Nevertheless, be aware that access policy is a crucial and integral architectural element when designing a REST API.