This sample demonstrates the annotations that are available within the Tribestream API and shows how to add them to a sample JAX-RS service.
The annotations themselves are split into two artifacts, tribestream-api-wadlx and tribestream-api-governance.
The tribestream-api-wadlx annotations provide a way to add documentation to the source code of your JAX-RS service. These annotations provide information at runtime that is rendered in the API registry, providing instant, up-to-date, beautiful documentation.
The tribestream-api-governance annotations allow you specify limits to the number of calls over a specific time period, and to the number of calls that can be made concurrently. Tribestream provides the functionality to apply these limits on a per-user and/or an all-user basis.
An addition to being able to provide a Web Application Description Language (WADL) file for your application at runtime, Tribestream is also able to provide an extended version of this, known as WADLx. This provides the information from the Tribestream annotations in your source code fully integrated with WADL. WADL is particularly useful for creating a client for your application, and WADLx provides the additional documentation and governance elements that will help your service consumer.
Tribestream provides a number of annotations that a service developer can add to the classes and methods in their application to describe its functionality, the type of output it provides, and more information about the parameters the service makes availble to clients.
At runtime, Tribestream will use these annotations to generate beautiful documentation for your application.
Here are all the annotations available:
APIs may introduce new methods or deprecate old ones as new versions are released. Service developers can use the @ApiVersion annotation to indicate which versions of the API the method is available in. API versions are specified as a String array on the annotation.
@GET
@Produces("application/json")
@Path("/configuration")
@ApiVersion({"1.1"})
@Description("Returns the current configuration used by Twitter including twitter.com slugs which are not usernames, maximum photo resolutions, and t.co URL lengths.")
public Response getConfiguration() {
//TODO: implementation
}
Specifies the categories that the resource appears in. A resource may belong to more than one category, by specifying all the categories the resource belongs to in the value attribute of the annotation. For example, a resource annotated with {@code @Category({ "account", "user" }}, will appear in both the account and user categories.
@GET
@Produces("application/json")
@Path("/settings")
@Category({"account"})
public Response getSettings() {
//TODO: implementation
}
The @Description allows you to provide a free-form textual description of what the resource actually does. This text is rendered as supplied in the documentation.
For example, a method with the following annotations:
@POST
@Produces("application/json")
@Path("/create")
@Description("Blocks the specified user from following the authenticating
user. In addition the blocked user will not show in the authenticating
users mentions or timeline (unless retweeted by another user). If a
follow or friend relationship exists it is destroyed.")
public Response postCreate(/* parameters here */) {
// TODO: implement this method
}
will render render using the text on the @Description annotation as shown below:
The @Descriptions annotation allows you to provide a number of @Description annotations with different values for a resource. For example, you may wish to provide different descriptions for different languages.
@POST
@Produces("application/json")
@Path("/create")
@Descriptions({
@Description(lang = "en", value = "Blocks the specified user from following the authenticating user."),
@Description(lang = "fr", value = "Bloque l' utilisateur spécifié de suivre l'utilisateur d'authentification .")
})
public Response postCreate(/* parameters here */) {
// TODO: implement this method
}
The text from each of the @Description annotations will be show in the documentation, in the order that the @Description annotations are specified on @Descriptions.
@Required is specified on a parameter of a service to mark it as mandatory.
In the example below, the user_id parameter is mandatory, while screen_name is optional.
@POST
@Produces("application/json")
@Path("/create")
public Response postCreate(@Description("The screen name of the potentially blocked user.")
@QueryParam("screen_name") final String screen_name, @Description("The ID of the potentially blocked user.")
@QueryParam("user_id") @Required final Integer user_id) {
//TODO: implement
return null;
}
Optional paramaters are highlighted in the documentation.
The @See annotation is much like the @see Javadoc annotation. It provideds a link to other documentation or resources that may be relevant to the resource.
Each @See annotation requires a href (the destination of the link) and value (the text that will displayed for the link).
@GET
@Produces("application/json")
@Path("/ids")
@See(href = "/docs/api/1.1/get/blocks/list", value = "GET blocks/list")
public Response getIds(/* parameters here */) {
//TODO: implement
return null;
}
Similar to the @Descriptions annotation, @SeeAlso allow multiples links to other documentation or resources to be added to a resource. Each @See link shown in the documentation in the order they are specified on the @SeeAlso annotation.
@GET
@Produces("application/json")
@Path("/list")
@SeeAlso({
@See(href = "/docs/api/1.1/get/blocks/ids", value = "GET blocks/ids"),
@See(href = "/docs/misc/cursoring", value = "Using cursors to navigate collections")
})
public Response getList(/* parameters here */) {
//TODO: implement
return null;
}
Indicates the current status of the resource. For example, if the signature of this resource has not yet been finalized, the developer of the resource may wish to indicate the resource as being in the draft status so the consumer of the API is aware it may change.
Available statuses are:
| Status | Description |
|---|---|
PROPOSAL |
A proposed service. May disappear or changed in the future. |
STUB |
A dummy implementation of the service. This may be provided for testing purposes. |
DRAFT |
A non-final version of the service. The definition may change in the future. |
TEST |
The service is available for testing purposes, and may not return live data. |
VALIDATION |
The service has been made available for validation purposes. |
ACCEPTED |
The service is stable and availble for consumption. |
CONFIDENTIAL |
Not for public consumption, and should not be shared with other parties. |
The @Tag annotation allows the developer to provide searchable keywords for the service. Keywords are specified as a String array on the annotation.
@GET
@Produces("application/json")
@Path("/lookup")
@Tag({"Bulk Operations", "finding users"})
@Description("Returns fully-hydrated user objects for up to 100 users per request, as specified by comma-separated values passed to the user_id and/or screen_name parameters.")
public UsersType getLookup(/* parameters here */) {
//TODO: implementation
}
Tribestream allows API providers to limit the number of concurrent requests and/ or the number of requests within a specified time window.
Both of these throttling limits can be applied at an application-wide level and user level.
When any of the rate limits are exceeded, Tribestream will respond to further requests with a HTTP 429 (Too Many Requests) response code.
The @Concurrent annotation allows the service developer to specify how many simultaneous invocations of the method can occur. This restriction can be applied per-user by adding @Concurrent to @UserLimit) or to all invocations (by adding @Concurrent to @ApplicationLimit).
@Concurrent takes one parameter, limit, which specifies the number of concurrent invocations allowed.
@Concurrent(limit = 200)
The example above would allow 200 concurrent invocations. By default, unlimited concurrent invocations are allowed.
The @Rate annotation allows the developer to control the number of invocations allowed within a specific time frame. The time frame is defined by the window and unit attributes. The units attribute uses the GovernaneUnit enumeration, which has the following values: SECONDS, MINUTES, HOURS, DAYS.
The limit attribute specifies the number of allowed invocations within the specified time frame.
So, for example to allow 200 calls per minute, the following could be used:
@Rate(window = 1, unit = GovernanceUnit.MINUTES, limit = 200) @Rate(window = 60, unit = GovernanceUnit.SECONDS, limit = 200)
To allow 1000 calls per hour, the following could be used:
@Rate(window = 1, unit = GovernanceUnit.HOURS, limit = 1000) @Rate(window = 60, unit = GovernanceUnit.MINUTES, limit = 1000)
@Rate, in the same way as @Concurrent, should be specified on the rate attribute of @ApplicationLimit and/or @UserLimit to apply the rate application-wide or on a per-user basis respectively.
Rates are enforced by counting the number of invocations from the first call. The count is reset on the first invocation after the window has passed. Therefore, if a rate of 15 calls per 15 minutes has been specified, you could not make say, 5 in each 15 minute block for 45 minutes, and then 45 in the next 15 minutes.
@Application limit allows the developer to provide @Rate and @Concurrent limits for the method that will apply across all invocations of the method, regardsless of the caller.
Specifying @ApplicationLimit for a method is optional, and by default, if @ApplicationLimit is not specified the unlimited invocations are permiited unless restricted by a @UserLimit. Both the rate and concurrent attributes are optional (and unlimited by default), so specifing @ApplicationLimit() (i.e. with no attributes) is the same as not adding @ApplicationLimit at all.
@GET
@Produces("application/json")
@Path("/configuration")
@ApplicationLimit(
rate = @Rate(window = 15, unit = GovernanceUnit.MINUTES, limit = 15),
concurrent = @Concurrent(limit = 5)
)
public Response getConfiguration() {
//TODO: implementation
}
In the example above, the method can be called up to 15 times in a 15 minute period, with up to 5 calls happening simultaneously.
The @UserLimit annotation follows the same structure as @ApplicationLimit, but applies the rate and concurrent settings on a per-user basis. So if the following annotations were applied:
@GET
@Produces("application/json")
@Path("/configuration")
@UserLimit(
rate = @Rate(window = 15, unit = GovernanceUnit.MINUTES, limit = 15),
concurrent = @Concurrent(limit = 2)
)
public Response getConfiguration() {
//TODO: implementation
}
both Bob and Alice could call this method 15 times every 15 minutes. If Bob exceeds the limit, Alice can still make her calls successfully until she reaches the limit.
Both Bob and Alice can make 2 simultaneous calls each.
Application and user limits are displayed in the documentation for the resource:
