cloudbees-event-api

Java client library to publish, read and query events.

An event can be published and queried for a Cloud Resource. A Service Platform resource or subscription is a cloud resource as well. The URL pattern is:

For Services Platform resource: CR URL: https://services-platform.cloudbees.com/api/services/resources/{service}/{account}/{resourceId}

CR type:https://types.cloudbees.com/resource/services-platform/resource

For Services Platform subscription:

CR URL: https://services-platform.cloudbees.com/api/services/subscriptions/{service}/{account}

CR type:https://types.cloudbees.com/resource/services-platform/subscription

Using the code

To use this library, add the following dependency to your Maven POM:

• Stable Release com.cloudbees.event cloudbees-event-api 1.1

• Snapshot

  com.cloudbees.event cloudbees-event-api 1.2-SNAPSHOT

Authentication

Event API require an OAuth token with following scopes:

* To publish an event https://api.cloudbees.com/services/api/events/write
* To read/Query an event https://api.cloudbees.com/services/api/events/read
* CloudResource READ capability scope. For example for a git CR, https://acme.org/testdb, the token must
  be granted with OAuth scope: crs://acme.org/!https://types.cloudbees.com/resource/read

Usage

    OauthClient oauthClient = new BeesClient(clientId,clientSecret).getOauthClient();
    TokenRequest tr = new TokenRequest();
            tr.withAccountName("cloudbees").withGenerateRequestToken(true)
                    .withScope(new URL("http://localhost:9090/vivek/websolr-play-sample"),
                            new Capability("https://types.cloudbees.com/resource/read"))
                    .withScope("https://api.cloudbees.com/services/api/events/write")
                    .withScope("https://api.cloudbees.com/services/api/events/read");

    // Generated token also carries refreshToken, store somewhere safe and next time around
    // call oauthClient.exchangeToAccessToken(refreshToken) to get new accessToken
    OauthToken token = oauthClient.createToken(tr);

    EventApi eventApi = new EventApi(token.accessToken);

Publish Event

The Target URL must identify the cloud resource.

    // Publish event events for an application on RUN@cloud as cloud resource
    Event.Target target = new Event.Target(new URL("https://services-platform.cloudbees.com/api/services/resources/cb-app/acme/helloworld"),
                                           "https://types.cloudbees.com/resource/services-platform/resource");

    Event eventReq = new Event(target, "info");

    Event.EventData eventData = new Event.EventData.Builder("Application helloworld deployed")
                    .description("Application helloworld event")
                    .url(new URL("https://run.cloudbees.com/a/acme"))
                    .build();

    eventReq.setEvent(eventData);

    //Returns Event URL, you can use this URL to get event detail
    String eventUrl = eventApi.publish(eventReq);

• Alternate way to Publish Event for a Services Platform Resource

Here we are using a different Target constructor providing service, account name and resourceId, everything else remains the same.

    // Publish event events for an application on RUN@cloud
    Event.Target target = new Event.Target.SpTargetBuilder("cb-app").
            resourceId("helloworld","cloudbees").
            resourceType("application").
            build();

• HTTP Request

   > POST https://services-platform.cloudbees.com/api/events/
   > Content-Type: application/json
   > Authorization: Bearer XXXXXXXXXXXX==
   {
     "target" : {
       "url" : "https://services-platform.cloudbees.com/api/services/resources/cb-app/acme/helloworld"
     },
     "type" : "info",
     "event" : {
       "title" : "Application helloworld deployed",
       "description" : "Application helloworld event",
       "url" : "https://run.cloudbees.com/a/acme"
     }
   }
  

• HTTP Response

   < 201
   < Date: Sun, 17 Nov 2013 20:33:13 GMT
   < Content-Length: 0
   < Location: https://services-platform.cloudbees.com/api/events/4e0fd0b48f744959b043dc11bd78f412
  

Read an event

    // Read an event,
    // using enventUrl with eventId,
    // for example https://services-platform.cloudbees.com/api/events/4e0fd0b48f744959b043dc11bd78f412
    Event event = eventApi.readEvent(eventUrl);

• HTTP Request

  > GET https://services-platform.cloudbees.com/api/events/4e0fd0b48f744959b043dc11bd78f412
  > Authorization: Bearer XXXXXXXXXXXX==
  

• HTTP Response

  < 200
  < Content-Type: application/json
  <
  {
    "type" : "info",
    "id" : "bf6d8e935fc143468c3e6b5b459ea330",
    "source" : {
      "url" : "https://services-platform.cloudbees.com/api/services/resources/cb-app/cloudbees/helloworld",
      "types" : [ "https://types.cloudbees.com/resource/services-platform/resource/application" ]
    },
    "event" : {
      "title" : "Application helloworld deployed",
      "description" : "Application helloworld event",
      "url" : "https://run.cloudbees.com/a/acme"
    },
    "activation_time" : 1384721849
  }
  

Delete event

    // Delete an event, eventUrl with event id
    // for example, https://services-platform.cloudbees.com/api/events/4e0fd0b48f744959b043dc11bd78f412
    eventApi.delete(eventUrl);

• HTTP Request

  > DELETE http://services-dev.apps.cloudbees.com/api/events/4e0fd0b48f744959b043dc11bd78f412
  > Authorization: Bearer XXXXXXXXXXXX==
  

• HTTP Response

  < 200
  < Date: Sun, 17 Nov 2013 20:33:13 GMT
  < Content-Length: 0
  

Query events

    //Build query using CR url
    QueryEventObject qeo = new QueryEventObject.QueryBuilder(eventApi.eventApiUrl)
            .cloudResource("https://services-platform.cloudbees.com/api/services/resources/cb-app/cloudbees/helloworld")
            .build();

• HTTP Request

  > GET https://services-platform.cloudbees.com/api/events/?cloud_resource=https://services-platform.cloudbees.com/api/services/resources/cb-app/cloudbees/helloworld
  > Authorization: Bearer XXXXXXXXXXXX==
  
  //Build query using SP specific parameters (account, service etc.)
  QueryEventObject qeo = new QueryEventObject.QueryBuilder(eventApi.eventApiUrl)
          .account("cloudbees")
          .service("cb-app")
          .resource("helloworld")
          .build();
  

• HTTP Request

  > GET http://services-dev.apps.cloudbees.com/api/events/?account=cloudbees&service=cb-app&resource=helloworld
  > Authorization: Bearer XXXXXXXXXXXX==
  
  // Execute query
  List<Event> events = eventApi.query(qeo.toUri());
  

• HTTP Response

  < 200
  < Content-Type: application/json
  
  [ {
    "type" : "info",
    "id" : "bf6d8e935fc143468c3e6b5b459ea330",
    "source" : {
      "url" : "https://services-dev.apps.cloudbees.com/api/services/resources/cb-app/cloudbees/helloworld",
      "types" : [ "https://types.cloudbees.com/resource/services-platform/resource/application" ]
    },
    "event" : {
      "title" : "Application helloworld deployed",
      "description" : "Application helloworld event",
      "url" : "https://run.cloudbees.com/a/acme"
    },
    "activation_time" : 1384721849
  } ]