# {{appName}} API Client

{{#appDescription}}

{{{.}}}
{{/appDescription}}

## Requirements

- [Java 8 JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
- [Apache Ant](http://ant.apache.org/) version 1.6 or later
- [Force.com Migration Tool](https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/forcemigrationtool_install.htm)
  - The `ant-salesforce.jar` file included with the Force.com Migration Tool must be placed in the root directory of this project (in the same directory as this README and `build.xml`)
- `ANT_HOME` and `JAVA_HOME` environment variables must be set accordingly
  - On Windows, `JAVA_HOME` will probably look something like this:

    ```cmd
    JAVA_HOME = C:\Program Files\Java\jdk1.8.0_121
    ```

- The `bin` directory from Ant must be on your `PATH`

If everything is set correctly:

- Running `java -version` in a command prompt should output something like:

  ```bash
  java version "1.8.0_121"
  Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
  Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
  ```

- Running `ant -version` should output something like:

  ```bash
  Apache Ant(TM) version 1.10.1 compiled on February 2 2017
  ```

For more information, see <https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/forcemigrationtool_prereq.htm>

## Installation

{{#gitRepoId}}{{#gitUserId}}

1. Clone the repo from GitHub

    ```bash
    git clone git@{{gitHost}}:{{gitUserId}}/{{gitRepoId}}.git
    ```

    Or, [download](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/archive/master.zip) the repo as a ZIP and extract it to `{{gitRepoId}}`
{{/gitUserId}}{{/gitRepoId}}

2. Set the `SF_USERNAME` and `SF_PASSWORD` environment variables to your Salesforce username and password. Alternatively, they may be set in `build.properties`. Environment variables will override the values in `build.properties` if set. `SF_SESSIONID` may also be set instead of `SF_USERNAME` and `SF_PASSWORD` (more info in `build.properties`)
3. Open up a command prompt in the root project directory {{#gitRepoId}}`{{.}}` {{/gitRepoId}}(the same directory as this README and `build.xml`)
4. Deploy to your Salesforce org

    ```bash
    ant deploy
    ```

    This command will:

    - deploy all classes in the `deploy/classes` directory to your Salesforce org
    - create a new [unmanaged package](https://help.salesforce.com/articleView?id=sharing_apps.htm) called **{{appName}} API Client**
    - execute all of the unit tests included in this package (at least 75% code coverage required)
    - create a new [remote site](https://help.salesforce.com/articleView?id=configuring_remoteproxy.htm) called **{{sanitizedName}}** configured for the endpoint: <{{basePath}}>
    - rolls back any changes upon any error

    A successful deployment will look like this:

    ```bash
    [sf:deploy] Request Status: Succeeded
    [sf:deploy] *********** DEPLOYMENT SUCCEEDED ***********
    [sf:deploy] Finished request 0Af7A00000Ebd5oSAB successfully.

    BUILD SUCCESSFUL
    Total time: 34 seconds
    ```

### Test deployment only

To perform a test deployment without committing changes:

```bash
ant deployCheckOnly
```

All of the included tests will run as if it were a real deployment. Tests and other validations will report back while leaving your org untouched, allowing you to verify that a deployment will succeed without affecting anything in the org.

### Uninstallation

```bash
ant undeploy
```

Removes all classes and the Remote Site created by this package.

## Getting Started

Please follow the [installation](#installation) instruction and execute the following Apex code:

```java{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
{{classname}} api = new {{classname}}();
{{#hasAuthMethods}}
{{classPrefix}}Client client = api.getClient();
{{#authMethods}}{{#isBasicBasic}}
// Configure HTTP basic authorization: {{{name}}}
HttpBasicAuth {{{name}}} = (HttpBasicAuth) client.getAuthentication('{{{name}}}');
{{{name}}}.setUsername('YOUR USERNAME');
{{{name}}}.setPassword('YOUR PASSWORD');

// You can also set your username and password in one line
{{{name}}}.setCredentials('YOUR USERNAME', 'YOUR PASSWORD');{{/isBasicBasic}}{{#isApiKey}}
// Configure API key authorization: {{{name}}}
ApiKeyAuth {{{name}}} = (ApiKeyAuth) client.getAuthentication('{{{name}}}');
{{{name}}}.setApiKey('YOUR API KEY');{{/isApiKey}}{{#isOAuth}}
// Configure OAuth2 access token for authorization: {{{name}}}
OAS.OAuth {{{name}}} = (OAS.OAuth) client.getAuthentication('{{{name}}}');
{{{name}}}.setAccessToken('YOUR ACCESS TOKEN');{{/isOAuth}}
{{/authMethods}}
{{/hasAuthMethods}}
{{#hasParams}}

Map<String, Object> params = new Map<String, Object>{
  {{#allParams}}
    '{{{paramName}}}' => {{{example}}}{{^-last}},{{/-last}}
  {{/allParams}}
};
{{/hasParams}}

try {
    // cross your fingers
    {{#returnType}}{{{.}}} result = {{/returnType}}api.{{{operationId}}}({{#hasParams}}params{{/hasParams}});
  {{#returnType}}
    System.debug(result);
  {{/returnType}}
} catch (OAS.ApiException e) {
    // ...handle your exceptions
}{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
```

## Documentation for API Endpoints

All URIs are relative to *{{basePath}}*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}}
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}

## Documentation for Models

{{#models}}{{#model}} - [{{classname}}]({{modelDocPath}}{{classname}}.md)
{{/model}}{{/models}}

## Documentation for Authorization

{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
{{#authMethods}}
### {{name}}

{{#isApiKey}}- **Type**: API key
- **API key parameter name**: {{keyParamName}}
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
{{/isApiKey}}
{{#isBasicBasic}}- **Type**: HTTP basic authentication
{{/isBasicBasic}}
{{#isBasicBearer}}- **Type**: HTTP Bearer Token authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
{{/isBasicBearer}}
{{#isHttpSignature}}- **Type**: HTTP signature authentication
{{/isHttpSignature}}
{{#isOAuth}}- **Type**: OAuth
- **Flow**: {{flow}}
- **Authorization URL**: {{authorizationUrl}}
- **Scopes**: {{^scopes}}N/A{{/scopes}}
{{#scopes}}  - {{scope}}: {{description}}
{{/scopes}}
{{/isOAuth}}

{{/authMethods}}

## Author

{{#apiInfo}}{{#apis}}{{#-last}}{{infoEmail}}
{{/-last}}{{/apis}}{{/apiInfo}}
