README.md

# Namecheap Elixir

Elixir client library for interacting with the [Namecheap API](https://www.namecheap.com/support/api/intro/).

The goal of this library is to facilitate the creation and management of domains.
We do not plan to implement all features (but merge requests are welcome).

```elixir
iex(1)> Namecheap.check_domains(["tribes.host", "us.xyz"])
{:ok,
 [
   %Namecheap.DomainCheckResult{
     available: false,
     description: "",
     domain: "tribes.host",
     eap_fee: #Decimal<0>,
     error_no: "0",
     icann_fee: #Decimal<0>,
     is_premium: false,
     premium_registration_price: #Decimal<0>,
     premium_renewal_price: #Decimal<0>,
     premium_restore_price: #Decimal<0>,
     premium_transfer_price: #Decimal<0>
   },
   %Namecheap.DomainCheckResult{
     available: true,
     description: "",
     domain: "us.xyz",
     eap_fee: #Decimal<0.0>,
     error_no: "0",
     icann_fee: #Decimal<0>,
     is_premium: true,
     premium_registration_price: #Decimal<13000.0>,
     premium_renewal_price: #Decimal<13000.0>,
     premium_restore_price: #Decimal<65.0>,
     premium_transfer_price: #Decimal<13000.0>
   }
 ]}
```

## About the Namecheap API

The Namecheap API has a single endpoint:

- `https://api.namecheap.com/xml.response`

All requests go through this one endpoint, using query strings to perform different operations.
All responses return XML data in a structured format.

There is not a 1:1 representation of XML in Elixir.
The closest thing we have is structs, but that can't discern attributes from content inside the tags.
As a result, this library creates abstractions over the XML entities returned by Namecheap, representing them as structs in a native format.

Requests are a bit easier because query params can be represented as maps.
Namecheap never requires you to send data in the request body, so we only ever need to parse XML *from* the response, never build it.

GET and POST work the same for all API operations, but the Namecheap docs [recommends using POST](https://www.namecheap.com/support/api/methods/domains/create/) for some operations, so we just use POST throughout the library.

## Installation

The package can be installed
by adding `namecheap` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:namecheap, "~> 0.1.0"}
  ]
end
```

### Configuration

You will then need to configure Namecheap for your application.

```elixir
import Config

config :namecheap,
  api_user: "example",
  api_key: "********************************",
  endpoint: "https://api.namecheap.com/xml.response"
```

#### Supported options

- `api_user` (**required**): Username of your Namecheap account.
- `api_key` (**required**): API key generated from your Namecheap account.
- `endpoint` (**required**): The endpoint to use for requests. You should set this to Namecheap's production endpoint in production, and their sandbox endpoint in development. There is no default for safety reasons.
- `user_name` (optional): Username on which each command is executed. Defaults to the value of `api_user`.
- `client_ip` (optional): [Nobody knows the purpose of this](https://www.namecheap.com/support/api/global-parameters/#comment-4726222840), but Namecheap requires it with every request. We pass the loopback address `127.0.0.1` by default, but feel free to override it.
- `parser` (optional): Any `Floki.HTMLParser` compatible parser module. Defaults to `Namecheap.Parser`.

## Usage

The `Namecheap` module contains functions for doing things in an Elixir-y way, but most features aren't implemented there yet.

However, it is possible to perform all API commands by calling `Namecheap.Client.command/3` directly.
For example:

```elixir
# Get a list of domains
Namecheap.Client.command(
  "namecheap.domains.getList",
  %{
    "ListType" => "ALL",
    "Page" => 2,
    "PageSize" => 50,
    "SortBy" => "NAME"
  },
  parser: Namecheap.NoOpParser
)
```

In this example we use the `Namecheap.NoOpParser`, which returns the raw XML response as a string.
The default parser works too, but does not support every type of entity yet.
You can use the default parser, implement your own parser, or set the parser to `Floki` if you just want an AST.

## License

Namecheap Elixir is licensed under the MIT license.
See `LICENSE.md` for a full copy of the license.