hipchat_elixir

HipChat client library for Elixir.

Generated from HipChat Swagger API specifications in ymtszw/hipchat_swagger.

Depends on hackney for HTTP client.

Policy

• No state. Access tokens and other credentials should be retrieved/stored by caller applications.
  • Although, hackney application does have some states.
• Relying HipChat cloud/server for parameter validations.
• Cover APIs used in server side only.

Basic Usage

1. Add :hipchat_elixir as a dependency.
2. Create client struct (Hipchat.ApiClient.new/3).
   • Pass access_token if the targeted API requires authentication.
   • access_token can be one of four types (according to the doc):
     • Add-on token
     • User token
     • Personal access token
     • Room notification token
   • See below for more
3. Pass the resultant client and other parameters to the targeted API function.

  Hipchat.ApiClient.new("access_token")
  |> Hipchat.V2.Rooms.send_room_notification("room_id", %{message: "Hello HipChat!"})
  # {:ok, %Hipchat.Httpc.Response{body: "", headers: ..., status: 204}}

About access_tokens

See here for complete coverage. Though a little explanations will not hurt so here they are:

Add-on token or User token Retrieval

They are automatically generated and retrieved after installations (in case of User tokens, upon users' approval, at least) .

To do that with this library:

1. Prepare your Add-on server with:
   • Installation Flow handling logics, which involves:
     • Capability descriptor endpoint URL
     • Stable storage for client_id and client_secret per installation
   • (For User token) Callback URL to which users are redirected after approval
2. Create an OAuth client struct (Hipchat.OauthClient.new/3) with generated client_id and client_secret.
3. Create a body which must include grant_type and other requirements.
   • grant_type should be:
     • client_credentials for Add-on token
     • authorization_code for initial retrieval of User tokens
     • refresh_token for refreshing User tokens
   • See here for details.
4. Request with OAuth Sessions API function.

  Hipchat.OauthClient.new("client_id", "client_secret")
  |> Hipchat.V2.OauthSessions.generate_token(%{grant_type: "client_credentials", scope: "send_notification"})
  # {:ok, %Hipchat.Httpc.Response{body: "<should contain access_token>", headers: ..., status: 200}}

1. Your server have to store generated access_tokens (and refresh_tokens) for later uses. If they expire, re-generate or refresh.

User generated tokens

After logging in to HipChat, you can manually generate Personal Access Tokens with arbitrary access scopes, or room-only Notification Tokens.

They are convenient because, (1) they do not require automatic installation logics on your server and, (2) they are semi-permanent (year-long expiration as of 2016/12).

If you just need notifications or other limited-scope actions in your Add-on or Bots, they come in very handy.

Be sure to properly control visibility of those tokens. They must be visible only to their owners and trusted third parties, as with any other similar API credentials out in the world.

Todo

• Generate other APIs.
• Helper client for handling OAuth client ID and secrets to retrieve short-lived Add-on token or User token.
  • Ready to be used. See Hipchat.OauthClient.

License

MIT