Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Connecting to a REST API

Mule DevKit simplifies the task of generating connectors for external entities with APIs that follow REST principles. For a processor that implements a single REST call, the @RestCall annotation works as in the following example.


         
      
1
2
3
@Processor
@RestCall(uri = "http://\{bucket\}.s3.amazonaws.com/?max-keys=0", method = HttpMethod.HEAD)
public abstract Object bucketExists(@RestUriParam("bucket") String bucketName);

The DevKit generates the entire REST call in a subclass that implements the abstract method. The generated code creates the URI based on the arguments of the @RestCall annotation and executes the specified HTTP method. The URI contains every item annotated with @RestUriParam. This means that the bucket portion of the URI is replaced with the contents of bucketName, because it is mapped with a @RestUriParam. You can use the @RestUriParam annotation on @Processor method arguments or @Configurable fields of the connector.

DevKit sends an unannotated argument and an argument annotated with @Payload as the body of the request call.

The generated code uses the connector HTTP client annotated with @RestHttpClient. The connector code must instantiate the client. If you do not annotate an HTTP client, Mule DevKit generates code to instantiate one of its own to use in making the call.

Inserting Query Parameters

The @RestQueryParam annotation identifies query parameters. As with the @RestUriParam, you can apply this annotation to @Processor method arguments or @Configurable fields of the connector. DevKit encodes each annotated query parameter and adds it to the query string in the call.

Inserting Post Parameters

The @RestPostParam annotation enables you to set parameters in the body of Post method calls. As with @RestQueryParam and @RestUriParam, this annotation applies to a @Processor method parameter or a @Configurable field. DevKit ensures that you apply this annotation only to Post methods.

Processor methods annotated with @RestPostParam cannot use a non-annotated argument or a @Payload annotated argument.

Inserting Headers

The @RestHeaderParam enables you to send custom headers in the call. As with @RestUriParam, apply this annotation to a @Processor method argument or a @Configurable field of the HTTP header specified in the annotation, as in the following example.


         
      
1
2
3
4
5
6
7
@RestHeaderParam("AuthorizationCode")
@Configurable
private String authorizationCode;
 
@Processor
@RestCall(uri = "http://\{bucket\}.s3.amazonaws.com/?max-keys=0", method = HttpMethod.HEAD)
public abstract Object bucketExists(@UriParam("bucket") String bucketName);

In this example, DevKit generates code that includes the Authorization header with the authorizationCode value in every @RestCall.

Identifying Failures

To determine whether a call is successful or not, use Mule Expressions to examine the output MuleMessage. The expression can be as simple as verifying the http.status code or complex as verifying specific portions of a JSON response, as in the following example.


         
      
1
2
3
@Processor
@RestCall(uri = "http://\{bucket\}.s3.amazonaws.com/?max-keys=0", method = HttpMethod.HEAD, exceptions="{@RestFailOn(expression = "#[header:http.status != 200]")}")
public abstract Object bucketExists(@UriParam("bucket") String bucketName);

Mule DevKit supports multiple @RestFailOn annotations to enable different behaviors according to the output of the rest call. DevKit generates code that throws an exception if the specified expression evaluates to true. You can optionally specify the exception to be thrown as an argument to the annotation. Otherwise, it throws RuntimeException.