<commit_before># Put it to REST!

[![Relaxing frog](docs/frog.jpg)](https://pixabay.com/en/frog-meadow-relaxed-relaxation-fig-1109795/)

[![Build Status](https://img.shields.io/travis/zalando/put-it-to-rest.svg)](https://travis-ci.org/zalando/put-it-to-rest)
[![Coverage Status](https://img.shields.io/coveralls/zalando/put-it-to-rest.svg)](https://coveralls.io/r/zalando/put-it-to-rest)
[![Release](https://img.shields.io/github/release/zalando/put-it-to-rest.svg)](https://github.com/zalando/put-it-to-rest/releases)
[![Maven Central](https://img.shields.io/maven-central/v/org.zalando/put-it-to-rest-parent.svg)](https://maven-badges.herokuapp.com/maven-central/org.zalando/put-it-to-rest)

Spring Boot REST client auto configuration

- **Technology stack**: Spring Boot
- **Status**:  Alpha

## Example

```yaml
rest.clients:
  example:
    base-url: http://example.com
    oauth.scopes:
      - example.read
```

```java
@Autowired
@Qualifier("example")
private Rest example;
```

## Features

Seamless integration of:
- [Riptide](https://github.com/zalando/riptide)
- [Logbook](https://github.com/zalando/logbook)
- [Tracer](https://github.com/zalando/tracer)
- [Tokens](https://github.com/zalando-stups/tokens)
- [STUPS Spring OAuth2 Client](https://github.com/zalando-stups/stups-spring-oauth2-support/tree/master/stups-spring-oauth2-client)
- [Jackson 2](https://github.com/FasterXML/jackson)

## Dependencies

- Java 8
- Any build tool using Maven Central, or direct download
- Spring Boot
- Apache HTTP Client

## Installation

Add the following dependency to your project:

```xml
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>put-it-to-rest</artifactId>
    <version>${put-it-to-rest.version}</version>
</dependency>
```

## Configuration

```yaml
rest:
  oauth:
    access-token-url: https://auth.example.com
    scheduling-period: 10
    timeouts:
      connect: 1
      read: 2
  clients:
    example:
      base-url: https://example.com
      oauth:
        scopes:
          - uid
          - example.read
      timeouts:
        connect: 5
        read: 5
```

### Client IDs, Bean Names and Qualifier

*example*, *exampleRestTemplate*, *example*
*exchange-rate*, *exchangeRateRestTemplate*, *exchange-rate*


| Configuration                        | Type            | Default                                            |
|--------------------------------------|-----------------|----------------------------------------------------|
| `rest.oauth.access-token-url`        | `URI`           | required, can be overridden by `ACCESS_TOKEN_URL`  |
| `rest.oauth.scheduling-period`       | `int` (seconds) | `5`                                                |
| `rest.oauth.timeouts.connect`        | `int` (seconds) | `1`                                                |
| `rest.oauth.timeouts.read`           | `int` (seconds) | `2`                                                |
| `rest.clients.<id>.base-url`         | `URI`           | none                                               |
| `rest.clients.<id>.oauth`            |                 | none, disables OAuth2 security if omitted          |
| `rest.clients.<id>.oauth.scopes`     | `List<String>`  | none                                               |
| `rest.clients.<id>.timeouts.connect` | `int` (seconds) | `5`                                                |
| `rest.clients.<id>.timeouts.read`    | `int` (seconds) | `5`                                                |

### Beans

| Bean Name                              | Bean Type                                   | Default                                        |
|----------------------------------------|---------------------------------------------|------------------------------------------------|
| `exampleHttpClient`                    | `HttpClient`                                | Configures interceptors                        |
| `exampleClientHttpRequestFactory`      | `ClientHttpRequestFactory`                  | Configures timeouts                            |
| `exampleHttpMessageConverters`         | `HttpMessageConverters`                     | Configures `text/plain` and `application/json` |
| `exampleRestTemplate`                  | `RestTemplate` or `StupsOAuth2RestTemplate` | Configures base URL and error handler          |
| `exampleRest`                          | `Rest`                                      |                                                |
| `exampleHttpAsyncClient`               | `HttpAsyncClient`                           | Configures interceptors                        |
| `exampleAsyncClientHttpRequestFactory` | `AsyncClientHttpRequestFactory`             | Configures timeouts                            |
| `exampleAsyncRestTemplate`             | `AsyncRestTemplate`                         |                                                |
| `exampleAsyncRest`                     | `AsyncRest`                                 |                                                |

`accessToken` `AccessTokens`

![Client Dependency Graph](docs/graph.png)

## Customization

- TODO overridable beans, by name

## Getting Help

If you have questions, concerns, bug reports, etc., please file an issue in this repository's
[Issue Tracker](issues).

## Getting Involved/Contributing

To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For
more details, check the [contribution guidelines](CONTRIBUTING.md).<commit_msg>Added more content to README<commit_after># Put it to REST!

[![Relaxing frog](docs/frog.jpg)](https://pixabay.com/en/frog-meadow-relaxed-relaxation-fig-1109795/)

[![Build Status](https://img.shields.io/travis/zalando/put-it-to-rest.svg)](https://travis-ci.org/zalando/put-it-to-rest)
[![Coverage Status](https://img.shields.io/coveralls/zalando/put-it-to-rest.svg)](https://coveralls.io/r/zalando/put-it-to-rest)
[![Release](https://img.shields.io/github/release/zalando/put-it-to-rest.svg)](https://github.com/zalando/put-it-to-rest/releases)
[![Maven Central](https://img.shields.io/maven-central/v/org.zalando/put-it-to-rest-parent.svg)](https://maven-badges.herokuapp.com/maven-central/org.zalando/put-it-to-rest)

Spring Boot REST client auto configuration

- **Technology stack**: Spring Boot
- **Status**:  Alpha

## Example

```yaml
rest.clients:
  example:
    base-url: http://example.com
    oauth.scopes:
      - example.read
```

```java
@Autowired
@Qualifier("example")
private Rest example;
```

## Features

- Seamless integration of:
  - [Riptide](https://github.com/zalando/riptide)
  - [Logbook](https://github.com/zalando/logbook)
  - [Tracer](https://github.com/zalando/tracer)
  - [Tokens](https://github.com/zalando-stups/tokens)
  - [STUPS Spring OAuth2 Client](https://github.com/zalando-stups/stups-spring-oauth2-support/tree/master/stups-spring-oauth2-client)
  - [Jackson 2](https://github.com/FasterXML/jackson)
- [Spring Boot](http://projects.spring.io/spring-boot/) Auto Configuration
- Sensible defaults

## Dependencies

- Java 8
- Any build tool using Maven Central, or direct download
- Spring Boot
- Apache HTTP Client

## Installation

Add the following dependency to your project:

```xml
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>put-it-to-rest</artifactId>
    <version>${put-it-to-rest.version}</version>
</dependency>
```

## Configuration

You can now define new REST clients and override default configuration in your `application.yml`:

```yaml
rest:
  oauth:
    access-token-url: https://auth.example.com
    scheduling-period: 10
    timeouts:
      connect: 1
      read: 2
  clients:
    example:
      base-url: https://example.com
      oauth:
        scopes:
          - uid
          - example.read
      timeouts:
        connect: 5
        read: 5
```

Clients are identified by a *Client ID*, for instance `example` in the sample above. You can have as many clients as you want.

For a complete overview of available properties, they type and default value please refer to the following table:

| Configuration                        | Type            | Default                                            |
|--------------------------------------|-----------------|----------------------------------------------------|
| `rest.oauth.access-token-url`        | `URI`           | required, can be overridden by `ACCESS_TOKEN_URL`  |
| `rest.oauth.scheduling-period`       | `int` (seconds) | `5`                                                |
| `rest.oauth.timeouts.connect`        | `int` (seconds) | `1`                                                |
| `rest.oauth.timeouts.read`           | `int` (seconds) | `2`                                                |
| `rest.clients.<id>.base-url`         | `URI`           | none                                               |
| `rest.clients.<id>.oauth`            |                 | none, disables OAuth2 security if omitted          |
| `rest.clients.<id>.oauth.scopes`     | `List<String>`  | none                                               |
| `rest.clients.<id>.timeouts.connect` | `int` (seconds) | `5`                                                |
| `rest.clients.<id>.timeouts.read`    | `int` (seconds) | `5`                                                |

## Usage

After configuring your clients, as shown in the last section, you can now easily inject them:

```java
@Autowired
@Qualifier("example")
private Rest example;
```

All beans that are created for each client use the *Client ID*, in this case `example`, as their qualifier.

Besides `Rest`, you can also alternatively inject any of the following types directly:
- `RestTemplate`
- `AsyncRest`
- `AsyncRestTemplate`

## Customization

For every client that is defined in your configuration the following graph of beans, indicated by the green color, will
be created:

![Client Dependency Graph](docs/graph.png)

Regarding the other colors:
- *yellow*: will be created once and then shared across different clients
- *red*: mandatory dependency
- *grey*: optional dependency

Every single bean in the graph can optionally be replaced by your own, custom version of it. Beans can only be
overridden by name, **not** by type. As an example, the following code would add XML support to the `example` client:

```java
@Bean
@Qualifier("example")
public HttpMessageConverters exampleHttpMessageConverters() {
    return new HttpMessageConverters(new Jaxb2RootElementHttpMessageConverter());
}
```

The following table shows all beans with their respective name (for the `example` client) and type:

| Bean Name                              | Bean Type                                   | Default                                        |
|----------------------------------------|---------------------------------------------|------------------------------------------------|
| `accessToken` (no client prefix!)      | `AccessTokens`                              | Configures OAuth settings                      |
| `exampleHttpClient`                    | `HttpClient`                                | Configures interceptors                        |
| `exampleClientHttpRequestFactory`      | `ClientHttpRequestFactory`                  | Configures timeouts                            |
| `exampleHttpMessageConverters`         | `HttpMessageConverters`                     | Configures `text/plain` and `application/json` |
| `exampleRestTemplate`                  | `RestTemplate` or `StupsOAuth2RestTemplate` | Configures base URL and error handler          |
| `exampleRest`                          | `Rest`                                      |                                                |
| `exampleHttpAsyncClient`               | `HttpAsyncClient`                           | Configures interceptors                        |
| `exampleAsyncClientHttpRequestFactory` | `AsyncClientHttpRequestFactory`             | Configures timeouts                            |
| `exampleAsyncRestTemplate`             | `AsyncRestTemplate`                         |                                                |
| `exampleAsyncRest`                     | `AsyncRest`                                 |                                                |

If you override a bean then all of its dependencies (see the [graph](#customization)), will **not** be registered,
unless required by some other bean.

## Getting Help

If you have questions, concerns, bug reports, etc., please file an issue in this repository's
[Issue Tracker](issues).

## Getting Involved/Contributing

To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For
more details, check the [contribution guidelines](CONTRIBUTING.md).
{'fraction_non_alphanumeric': 0.15213648458287682, 'fraction_numerical': 0.004304272969165753, 'mean_word_length': 1.7011202705559079, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 31, 'https://': 34, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 62, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '551184', 'n_tokens_mistral': 3486, 'n_tokens_neox': 3304, 'n_words': 781}