Definition – Conventions – Hands-On

Definition

"Representational state transfer (REST) is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system."

Conventions

• Welche Methode?
• Benennung der Ressourcen
• Naming im JSON
• Request Payload

Welche Methode?

POST GET PUT DELETE

!=

CRUD

GET & DELETE

Entspricht dem READ und DELETE von CRUD.

GET     http://transport.opendata.ch/v1/stations
DELETE  http://transport.opendata.ch/v1/stations/1234

POST & PUT

Beide Methoden können für CREATE und UPDATE verwendet werden.

POST http://transport.opendata.ch/v1/stations

{
    name : "Zürich Hauptbahnhof"
}

PUT http://transport.opendata.ch/v1/stations/8765

{
    name : "Zürich Hauptbahnhof"
}

WTF?

POST & PUT

Der Schlüssel liegt in der Idempotenz

"Send and send and send my friend, it makes no difference in the end."

- James Beninger

POST & PUT

POST ist nicht idempotent:

POST http://transport.opendata.ch/v1/stations

{
    name : "Zürich Hauptbahnhof"
}

==>
201 Created
Location: /stations/4444

Was passiert, wenn ich diesen Request mehrmals ausführe?

POST & PUT

POST http://transport.opendata.ch/v1/stations

{
    name : "Zürich Hauptbahnhof"
}

==>
201 Created
Location: /stations/4444

and again!

POST http://transport.opendata.ch/v1/stations

{
    name : "Zürich Hauptbahnhof"
}

==>
201 Created
Location: /stations/4445

POST & PUT

PUT ist idempotent:

PUT http://transport.opendata.ch/v1/stations/4444

{
    name : "Zürich Hauptbahnhof"
}

==>
201 Created
Location: /stations/4444

Was passiert, wenn ich diesen Request mehrmals ausführe?

POST & PUT

PUT http://transport.opendata.ch/v1/stations/4444

{
    name : "Zürich Hauptbahnhof"
}

==>
201 Created
Location: /stations/4444

and again!

PUT http://transport.opendata.ch/v1/stations/4444

{
    name : "Zürich Hauptbahnhof"
}

==>
201 Created
Location: /stations/4444

POST & PUT

Bei POST lassen wir den Server entscheiden, unter welcher Location die Resource erstellt wird.

Bei PUT sagen wir dem Server, unter welcher Location die Resource erstellt/überschrieben werden soll.

PUT     http://transport.opendata.ch/v1/locations/4444
POST    http://transport.opendata.ch/v1/locations

Achtung: Natürlich liegt es an der Implementation des Servers, ob PUT & POST auch wirklich idempotent ist oder nicht!

POST

POST darf verwendet werden, wenn die Query Parameter eine gefährlich grosse Länge annehmen könnten. Zum Beispiel, wenn ich n Rufnummern einem Standort zuweisen möchte:

PUT    /numbers/1,2,3,4,5,6,7,...,756879895 

{
    "locationId" : 1337
}

POST    /numbers/locationAssignment

{
    "numberIds" : [ 1,2,3,... ],
    "locationId" : 1337
}

Benennung der Ressourcen

Verwende immer Nomen, um die Ressourcen zu benennen.

Verwende immer Plural, ausser es handelt sich wirklich um eine einzelne Ressource und nicht eine Collection.

Benennung der Ressourcen

Wir exposen mit einer REST API die Ressource =Nomen

und nicht die Operationen darauf =Verben

Die HTTP Methode sagt uns, was wir auf dieser Ressource tun.

POST    /locations                  // DO

POST    /locations/createLocation   // DON'T

DELETE  /locations/1234             // DO

DELETE  /deleteLocation/1234        // DON'T

JSON

// nope

{
    employee : {
        employeeId   : 111,
        employeeName : "John"
    }
}

skip the prefix!

{
    employee : {
        id      : 111,
        name    : "John"
    }
}

Request Payloads

GET und DELETE haben keinen Payload.

Einschränkungen für die Antwort (z.B. search-parameters) gehören in die URL-Parameter.

GET /locations?canton=Aargau&county=Baden

                        

Hands-On

Design your API

REST @ SAM

JAX-RS with Jersey

Automatisches Serialisieren und Deserialisieren

• JSON mit Jackson
• XML mit JAXB

Der Accept-Header gibt an, wie die Antwort aussehen soll.

Accept: application/json
Accept: application/xml

                        

Serializing and Deserializing

Beispiel

                        
GET     /employees

Accept: application/json
 

@GET
public Employee[] getEmployees() { ... }

==>
[{ name : "John Wayne" }, ..., ]

                        

Base Path

@Path("/regservice/employees")
public class EmployeeRestService { ... }

                        

Path Params

Client:

GET /employees/1234

                        

Server:

@GET
@Path("/{employeeId}")
public Employee getEmployee(@PathParam("employeeId")
        String employeeId)

==>
{ id : "1234", name : "John Wayne" }

                        

Query Params

Client:

GET /employees?name=John

                        

Server:

@GET
public Employee getEmployees(@QueryParam("name") 
        String name)

==>
{ id : "1234", name : "John Wayne" }

                        

Request Payload

Client:

POST /employees
{
    name : "Chuck Norris"
}

Server:

@POST
public void createEmployee(Employee employee)

==>
204 No Content

Postman

Live Demo

Hands On!

Deep Dive

• Expand
• Patch
• Head
• Options
• Versioning
• Error Handling
• HATEOAS