Overview

HTTP verbs

Grails RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

Grails RESTful notes tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

Resources

Index

The index provides the entry point into the service.

Accessing the index

A GET request is used to access the index

Example request

$ curl 'http://api.example.com/' -i -H 'Accept: application/json'

Response structure

Path Type Description

message

String

Welcome to Grails!

environment

String

The running environment

appversion

String

version of the app that is running

grailsversion

String

the version of grails used in this project

appprofile

String

the profile of grails used in this project

groovyversion

String

the version of groovy used in this project

jvmversion

String

the version of the jvm used in this project

controllers

Array

the list of available controllers

plugins

Array

the plugins active for this project

Example response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Application-Context: application:test
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 18 Mar 2016 15:40:54 GMT
Content-Length: 1287

{
  "message" : "Welcome to Grails!",
  "environment" : "test",
  "appversion" : "0.1",
  "grailsversion" : "3.0.15",
  "appprofile" : "web-api",
  "groovyversion" : "2.4.5",
  "jvmversion" : "1.8.0_73",
  "controllers" : [ {
    "name" : "com.example.NoteController"
  }, {
    "name" : "com.example.InternalServerErrorController"
  }, {
    "name" : "com.example.TagController"
  }, {
    "name" : "com.example.NotFoundController"
  }, {
    "name" : "com.example.IndexController"
  } ],
  "plugins" : [ {
    "name" : "restResponder-3.0.15"
  }, {
    "name" : "eventBus-3.0.15"
  }, {
    "name" : "geb-1.0.0"
  }, {
    "name" : "core-3.0.15"
  }, {
    "name" : "i18n-3.0.15"
  }, {
    "name" : "dataBinding-3.0.15"
  }, {
    "name" : "controllers-3.0.15"
  }, {
    "name" : "urlMappings-3.0.15"
  }, {
    "name" : "dataSource-3.0.15"
  }, {
    "name" : "codecs-3.0.15"
  }, {
    "name" : "domainClass-3.0.15"
  }, {
    "name" : "converters-3.0.15"
  }, {
    "name" : "hibernate-4.3.10.7"
  }, {
    "name" : "controllersAsync-3.0.15"
  }, {
    "name" : "filters-3.0.15"
  }, {
    "name" : "groovyPages-3.0.15"
  }, {
    "name" : "interceptors-3.0.15"
  }, {
    "name" : "mimeTypes-3.0.15"
  }, {
    "name" : "services-3.0.15"
  }, {
    "name" : "cache-3.0.2"
  } ]
}

Notes

The Notes resources is used to create and list notes

Listing notes

A GET request will list all of the service’s notes.

Response structure

Path Type Description

[].class

String

the class of the resource

[].id

Number

the id of the note

[].title

String

the title of the note

[].body

String

the body of the note

[].tags

Array

the list of tags associated with the note

Example request

$ curl 'http://api.example.com/notes' -i -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Application-Context: application:test
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 18 Mar 2016 15:40:54 GMT
Content-Length: 141

[ {
  "class" : "com.example.Note",
  "id" : 1,
  "body" : "Hello from the Integration Test",
  "tags" : [ ],
  "title" : "Hello, World!"
} ]

Creating a note

A POST request is used to create a note

Request structure

Path Type Description

title

String

the title of the note

body

String

the body of the note

tags

Array

a list of tags associated to the note

Example request

$ curl 'http://api.example.com/notes' -i -X POST -H 'Accept: application/json' -H 'Content-Type: application/json; charset=UTF-8' -d '{ "body": "My test example", "title": "Eureka!", "tags": [{"name": "testing123"}] }'

Example response

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
X-Application-Context: application:test
Location: http://localhost:8080/notes/2
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 18 Mar 2016 15:40:54 GMT
Content-Length: 167

{
  "class" : "com.example.Note",
  "id" : 2,
  "body" : "My test example",
  "tags" : [ {
    "class" : "com.example.Tag",
    "id" : 1
  } ],
  "title" : "Eureka!"
}

Retrieve a note

A GET request will retrieve the details of a note

Response structure

Path Type Description

class

String

the class of the resource

id

Number

the id of the note

title

String

the title of the note

body

String

the body of the note

tags

Array

the list of tags associated with the note

Example request

$ curl 'http://api.example.com/notes/1' -i -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Application-Context: application:test
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Fri, 18 Mar 2016 15:40:54 GMT
Content-Length: 137

{
  "class" : "com.example.Note",
  "id" : 1,
  "body" : "Hello from the Integration Test",
  "tags" : [ ],
  "title" : "Hello, World!"
}