CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-typesafe-play--play-ws-2-10

Asynchronous HTTP client for Play Framework with OAuth, OpenID, and SSL/TLS support

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Play WS

Play WS is a powerful asynchronous HTTP client library for the Play Framework. It provides comprehensive WebService client functionality built on top of the Ning AsyncHttpClient, supporting OAuth authentication, OpenID authentication, SSL/TLS configuration, and seamless integration with Play's reactive streaming model.

Package Information

  • Package Name: play-ws_2.10
  • Package Type: maven
  • Language: Scala/Java
  • Installation:
    • Scala: Add to build.sbt: "com.typesafe.play" %% "play-ws" % "2.4.11"
    • Java: Add to build.sbt: "com.typesafe.play" % "play-java-ws_2.10" % "2.4.11"

Core Imports

Scala API

import play.api.libs.ws._
import play.api.libs.ws.ning._
import play.api.Application
import scala.concurrent.Future

For dependency injection:

import javax.inject.Inject
import play.api.libs.ws.WSClient

class MyService @Inject()(ws: WSClient) {
  // Use ws client
}

Java API

import play.libs.ws.*;
import play.libs.F.Promise;
import java.util.concurrent.CompletionStage;

For dependency injection:

import javax.inject.Inject;
import play.libs.ws.WSClient;

public class MyService {
    private final WSClient ws;
    
    @Inject
    public MyService(WSClient ws) {
        this.ws = ws;
    }
}

Basic Usage

Scala API

import play.api.libs.ws._
import play.api.Application
import scala.concurrent.Future
import scala.concurrent.ExecutionContext.Implicits.global

implicit val app: Application = // Your Play application

// Simple GET request
val futureResponse: Future[WSResponse] = WS.url("https://api.example.com/users").get()

// POST with JSON body
val jsonData = Json.obj("name" -> "John", "email" -> "john@example.com")
val postResponse: Future[WSResponse] = WS.url("https://api.example.com/users")
  .withHeaders("Content-Type" -> "application/json")
  .post(jsonData)

// Handle response
futureResponse.map { response =>
  println(s"Status: ${response.status}")
  println(s"Body: ${response.body}")
  val jsonBody = response.json
}

Java API

import play.libs.ws.*;
import play.libs.F.Promise;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import play.libs.Json;

// Simple GET request
Promise<WSResponse> responsePromise = WS.url("https://api.example.com/users").get();

// POST with JSON body
ObjectNode jsonData = Json.newObject();
jsonData.put("name", "John");
jsonData.put("email", "john@example.com");

Promise<WSResponse> postPromise = WS.url("https://api.example.com/users")
    .setHeader("Content-Type", "application/json")
    .post(jsonData);

// Handle response
responsePromise.map(response -> {
    System.out.println("Status: " + response.getStatus());
    System.out.println("Body: " + response.getBody());
    JsonNode jsonBody = response.asJson();
    return response;
});

Architecture

Play WS is built around several key components:

  • Core HTTP Client: WS, WSClient, WSRequest, and WSResponse providing the main HTTP client API
  • Ning Implementation: NingWSClient providing the actual HTTP implementation using Ning AsyncHttpClient
  • Authentication: OAuth 1.0a and OpenID support for secure API access
  • SSL/TLS Configuration: Comprehensive SSL configuration system for secure connections
  • Reactive Streaming: Integration with Play's iteratees for streaming large responses
  • Dependency Injection: Full support for Play's dependency injection system

Capabilities

HTTP Client Operations

Core HTTP client functionality for making RESTful API calls, handling responses, and managing connection settings.

Scala API

object WS {
  def client(implicit app: Application): WSClient
  def url(url: String)(implicit app: Application): WSRequest
  def clientUrl(url: String)(implicit client: WSClient): WSRequest
}

trait WSClient {
  def underlying[T]: T
  def url(url: String): WSRequest
  def close(): Unit
}

trait WSRequest {
  def get(): Future[WSResponse]
  def post[T](body: T)(implicit wrt: Writeable[T]): Future[WSResponse]
  def put[T](body: T)(implicit wrt: Writeable[T]): Future[WSResponse]
  def patch[T](body: T)(implicit wrt: Writeable[T]): Future[WSResponse]
  def delete(): Future[WSResponse]
  def head(): Future[WSResponse]
  def options(): Future[WSResponse]
}

Java API

public class WS {
  public static WSClient client()
  public static WSRequest url(String url)
  public static WSClient newClient(int port)
}

public interface WSClient extends Closeable {
  WSRequest url(String url)
  Object getUnderlying()
  void close()
}

public interface WSRequest {
  Promise<WSResponse> get()
  Promise<WSResponse> post(Object body)
  Promise<WSResponse> put(Object body) 
  Promise<WSResponse> patch(Object body)
  Promise<WSResponse> delete()
  Promise<WSResponse> head()
  Promise<WSResponse> options()
  Promise<WSResponse> execute()
  WSRequest setHeader(String name, String value)
  WSRequest setQueryParameter(String name, String value)
  WSRequest setAuth(String username, String password, WSAuthScheme scheme)
  WSRequest setBody(Object body)
  WSRequest setMethod(String method)
}

HTTP Client

OAuth Authentication

OAuth 1.0a authentication support for secure API access with consumer keys and request tokens.

case class OAuth(info: ServiceInfo, use10a: Boolean = true) {
  def retrieveRequestToken(callbackURL: String): Either[OAuthException, RequestToken]
  def retrieveAccessToken(token: RequestToken, verifier: String): Either[OAuthException, RequestToken]
  def redirectUrl(token: String): String
}

case class OAuthCalculator(consumerKey: ConsumerKey, requestToken: RequestToken) extends WSSignatureCalculator

OAuth Authentication

OpenID Authentication

OpenID authentication support for identity verification and user attribute exchange.

object OpenID {
  def redirectURL(
    openID: String,
    callbackURL: String,
    axRequired: Seq[(String, String)] = Seq.empty,
    axOptional: Seq[(String, String)] = Seq.empty,
    realm: Option[String] = None
  )(implicit app: Application): Future[String]
  
  def verifiedId(implicit request: Request[_], app: Application): Future[UserInfo]
}

OpenID Authentication

SSL/TLS Configuration

Comprehensive SSL and TLS configuration system for secure HTTPS connections with custom certificates, protocols, and security settings.

case class SSLConfig(
  default: Boolean = false,
  protocol: String = "TLSv1.2",
  enabledProtocols: Option[Seq[String]] = Some(Seq("TLSv1.2", "TLSv1.1", "TLSv1")),
  enabledCipherSuites: Option[Seq[String]] = None,
  keyManagerConfig: KeyManagerConfig = KeyManagerConfig(),
  trustManagerConfig: TrustManagerConfig = TrustManagerConfig(),
  debug: SSLDebugConfig = SSLDebugConfig(),
  loose: SSLLooseConfig = SSLLooseConfig()
)

SSL Configuration

Ning HTTP Client Implementation

Ning AsyncHttpClient-based implementation providing the actual HTTP transport layer with advanced configuration options.

case class NingWSClient(config: AsyncHttpClientConfig) extends WSClient {
  def url(url: String): WSRequest
  def close(): Unit
}

case class NingWSClientConfig(
  wsClientConfig: WSClientConfig = WSClientConfig(),
  allowPoolingConnection: Boolean = true,
  maxConnectionsPerHost: Int = -1,
  maxConnectionsTotal: Int = -1
)

Ning Implementation

Test Support

Testing utilities for HTTP client operations in Play applications.

trait WsTestClient {
  def wsCall(call: Call)(implicit port: Port, client: WSClient): WSRequest
  def wsUrl(url: String)(implicit port: Port, client: WSClient): WSRequest
  def withClient[T](block: WSClient => T)(implicit port: play.api.http.Port): T
}

Test Support

Types

Scala API Types

trait WSResponse {
  def status: Int
  def statusText: String
  def header(key: String): Option[String]
  def allHeaders: Map[String, Seq[String]]
  def cookies: Seq[WSCookie]
  def cookie(name: String): Option[WSCookie]
  def body: String
  def xml: Elem
  def json: JsValue
  def bodyAsBytes: Array[Byte]
}

trait WSCookie {
  def name: String
  def value: String
  def domain: String
  def path: Option[String]
  def maxAge: Option[Long]
  def secure: Boolean
  def httpOnly: Boolean
}

sealed trait WSBody
case class InMemoryBody(bytes: Array[Byte]) extends WSBody
case class FileBody(file: File) extends WSBody
case class StreamedBody(bytes: Enumerator[Array[Byte]]) extends WSBody
case object EmptyBody extends WSBody

case class WSClientConfig(
  connectionTimeout: Duration = 2.minutes,
  idleTimeout: Duration = 2.minutes,
  requestTimeout: Duration = 2.minutes,
  followRedirects: Boolean = true,
  useProxyProperties: Boolean = true,
  userAgent: Option[String] = None,
  compressionEnabled: Boolean = false,
  ssl: SSLConfig = SSLConfig()
)

trait WSProxyServer {
  def host: String
  def port: Int
  def protocol: Option[String]
  def principal: Option[String]
  def password: Option[String]
}

sealed trait WSAuthScheme
object WSAuthScheme {
  case object BASIC extends WSAuthScheme
  case object DIGEST extends WSAuthScheme
  case object NTLM extends WSAuthScheme
  case object SPNEGO extends WSAuthScheme
  case object KERBEROS extends WSAuthScheme
  case object NONE extends WSAuthScheme
}

Java API Types

public interface WSResponse {
  int getStatus()
  String getStatusText()
  String getHeader(String key)
  Map<String, List<String>> getAllHeaders()
  List<WSCookie> getCookies()
  WSCookie getCookie(String name)
  String getBody()
  Document asXml()
  JsonNode asJson()
  InputStream getBodyAsStream()
  byte[] asByteArray()
}

public interface WSCookie {
  String getName()
  String getValue()
  String getDomain()
  String getPath()
  Long getMaxAge()
  Boolean isSecure()
  Boolean isHttpOnly()
}

public enum WSAuthScheme {
  BASIC, DIGEST, NTLM, SPNEGO, KERBEROS, NONE
}

docs

http-client.md

index.md

ning.md

oauth.md

openid.md

ssl.md

testing.md

tile.json