SimpleRestService (Jervis 2.2 API)

net.gleske.jervis.remotes.SimpleRestService

A simple class which makes using REST services like the GitHub API really easy. This utilizes helpful features of Groovy while not relying on any heavier external libraries for HTTP communication.

Sample usage

To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.

A basic get request

By default, JSON-based REST APIs are assumed. The response will automatically be parsed into a plain Java Object. In this example, a HashMap is returned.


import net.gleske.jervis.remotes.SimpleRestService

SimpleRestService.apiFetch(new URL('https://api.github.com/meta'))

A basic get request with no response processing

So if you do not set the content type, then an application/json response will be assumed. If you do not want any response processing you can force no content type by passing a null HTTP request header value for Content-Type.


import net.gleske.jervis.remotes.SimpleRestService

SimpleRestService.apiFetch(new URL('http://www.example.com/'), ['Content-Type': null])

Handling binary data

This client can send or receive binary data by using a special header Binary-Data. Compare this example with GZip


import java.net.HttpURLConnection
import net.gleske.jervis.remotes.SimpleRestService
import net.gleske.jervis.tools.GZip
import net.gleske.jervis.tools.SecurityIO

String username = 'some user'
String password = 'some pass'

// this example data will be compressed and uploaded to Nexus
String upload_data = 'hello world\n\nMy friend\n'

URL api_url = new URL('http://localhost:8081/repository/hosted-raw-repo/file.gz')
Map http_headers = [
    Authorization: "Basic ${SecurityIO.encodeBase64("${username}:${password}")}",
    Accept: '*/*',
    Expect: '100-continue',
    'Binary-Data': true
]

// make network call uploading or receiving binary data
HttpURLConnection response = SimpleRestService.apiFetch(
        api_url,
        http_headers,
        'PUT',
        'binary-data') { httpOutputStream ->

    // wrap the output stream with compression
    new GZip(httpOutputStream).withCloseable { gzip ->
        gzip << upload_data
    }
}

// get response message from Nexus
response.getHeaderFields()[null][0]

You can also use the Binary-Data special header to get back the raw HTTP request response so you can do your own custom processing.


import net.gleske.jervis.remotes.SimpleRestService

SimpleRestService.apiFetch(new URL('http://www.example.com/'), ['Binary-Data': true])

You would also do a similar request to download compressed data you uploaded to Nexus.


import java.net.HttpURLConnection
import java.util.zip.GZIPInputStream
import net.gleske.jervis.remotes.SimpleRestService

URL api_url = new URL('http://localhost:8081/repository/hosted-raw-repo/file.gz')
HttpURLConnection response = SimpleRestService.apiFetch(api_url, ['Binary-Data': true])
ByteArrayOutputStream plain = new ByteArrayOutputStream()

response.inputStream.withCloseable { is ->
    new GZIPInputStream(is).withCloseable { gunzip ->
        // decompress the downloaded text
        plain << gunzip
    }
}
assert plain.toString() == 'hello world\n\nMy friend\n'

Methods Summary

Methods
Type Params	Return Type	Name and description
	`static String`	`addTrailingSlash(String url, String suffix = '')` Meant for flexibly setting API URLs, this will enforce a trailing slash and optionaly a suffix such as an API version applied to the URL.
	`static def`	`apiFetch(URL api_url, Map http_headers = [:], String http_method = 'GET', def data = '', Closure httpOutputStream = null)` `apiFetch()` can be used to submit HTTP commands common to REST APIs.
	`static String`	`objToJson(def obj)` A method for converting an object comprising of standard Java classes `Map` or `List` to a JSON String.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`equals, toString, hashCode, getClass, notify, notifyAll, wait, wait, wait`

- Method Detail
  - static String addTrailingSlash(String url, String suffix = '')
    
    Meant for flexibly setting API URLs, this will enforce a trailing slash and optionaly a suffix such as an API version applied to the URL.
    Parameters:
    url - Typically an API URL where a trailing slash will be added if missing.
    suffix - Typically an API version path where a trailing slash will be added if missing. If this option is provided, then it will ensure url ends with the suffix and add it if missing.
  - static def apiFetch(URL api_url, Map http_headers = [:], String http_method = 'GET', def data = '', Closure httpOutputStream = null)
    
    apiFetch() can be used to submit HTTP commands common to REST APIs. If http_headers does not contain a Content-Type header, then application/json is assumed.
    Extra behaviors are provided by special http_headers. These headers are not sent over HTTP but instead change the behavior of the response.
    
    Special HTTP Headers:
    
    Binary-Data - Enable send and receive of binary data. No Content-Type is set and no automatic response processing is performed. An HttpURLConnection will always be returned. All other special HTTP headers will be ignored.
    
    Parse-JSON - For JSON-based APIs responses are automatically parsed. This setting can disable automatic parsing if set to false.
    
    Response-Code - Return the HTTP response code.
    
    Response-Headers - Return the HTTP response headers as an unmodifiable Map. The DELETE HTTP method requires setting Response-Code to false. The HEAD HTTP method implies returning response headers.
    
    Response-Map - Return a HashMap containing response_code, response_headers, response_content, and error keys. error will return true if response_code is a 4XX or 5XX HTTP code.
    
    Parameters:
    api_url - A URL of a REST endpoint in which to make an HTTP call.
    http_headers - HTTP headers to pass as part of the HTTP request. By default only Content-Type: application/json HTTP header will be set.
    http_method - The HTTP method or action to request from the server. Currently supported methods include: GET, POST, PUT, DELETE, and PATCH.
    data - Send String data to the remote connection via OutputStream Writer.
    httpOutputStream - A Closure in which an OutputStream is passed as an argument. This allows caller to write binary data to the remote as part of the HTTP connection. The httpOutputStream will only be called if data is a non-zero length String.
    Returns:
    If Content-Type HTTP header is application/json, then one of two types will be returned: HashMap or ArrayList (for JSON Object and JSON Array respectively). If any other Content-Type HTTP header used then a String will be returned and it will be left up to the caller to parse the result. If Binary-Data request header was passed, then an HttpURLConnection will be returned and all response processing will be left to the caller.
  - static String objToJson(def obj)
    
    A method for converting an object comprising of standard Java classes Map or List to a JSON String.
    Parameters:
    obj - Any object.
    Returns:
    A String of JSON text which could be later parsed if the obj is a Map or List. Otherwise, the original object is returned if serialization is not possible.

Summary:
Method

| Detail:
Method

Jervis API documentation.

[Groovy] Class SimpleRestService

Sample usage

A basic get request

A basic get request with no response processing

Handling binary data

Methods Summary

Inherited Methods Summary

Method Detail

static String addTrailingSlash(String url, String suffix = '')

static def apiFetch(URL api_url, Map http_headers = [:], String http_method = 'GET', def data = '', Closure httpOutputStream = null)

static String objToJson(def obj)