Skip to content
This repository has been archived by the owner on Mar 13, 2024. It is now read-only.

Commit

Permalink
feat(all): simplified endpoint development
Browse files Browse the repository at this point in the history 
BREAKING CHANGE: Unfortunately, working with version 1 of the Cloudflare
bindings was a pain. As users, you were subject to a weird API
structure, strict—and often incorrect—local validation logic, and having
to use a client that was missing most of the API endpoints. For me
(hi!), it was hard to get validation logic accurate, keeping the models
complete, and adding support for the entire API.

This pre-release introduces a ground-up rewrite of the bindings to
address these issues.

* Endpoints and methods are now generated from a simple specification.
* Removal of those pesky model objects and the inaccurate validation
  logic they contained.
* Methods are now directly on the resource objects.
* Faster (and more direct) unit tests using testdouble.
* You can now provide authentication when calling resource methods,
  which overrides the client's authentication, and "User Service Keys"
  are completely supported.
  • Loading branch information
@terinjokes
terinjokes committed Dec 30, 2016
1 parent a00c0d2 commit 8bbdc0a
Show file tree
Hide file tree
Showing 23 changed files with 884 additions and 1,366 deletions.
1 change: 1 addition & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
Copyright (C) 2014 Cloudflare, Inc.
Portions of lib/method.js adapted from stripe-node, Copyright (C) 2013 Stripe, Inc. (https://stripe.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
258 changes: 50 additions & 208 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,231 +1,73 @@
# CloudFlare API Client for Node.js
# Cloudflare Node.js bindings

An edible "BREAD" (Browse, Read, Edit, Add, and Delete) API Client for the
CloudFlare v4 Client API.
[Cloudflare v4 API][cf-api] bindings for Node.js, providing a sourdough
"BREAD" (Browse, Read, Edit, Add, and Delete) interface.

With this API client, you'll get the following features:
[cf-api]: https://api.cloudflare.com/

* Promise-based API, allowing for easy async/await usage in harmony JavaScript
engines, and with JavaScript transpilers.
* Effortlessly connects over HTTP/2.
With these bindings, you'll get the following features:

* A Promise-based API. With modern versions of Node.js, this can be
leveraged for async/await and generator support.
* Effortless connections over HTTP/2.
* Automatic handling of Gzip/Deflate compression.
* Expontential backoff and retry in the presence of error.

## Node.js Support
Node.js v4 and greater are supported.

This CloudFlare API client supports Node.js v4 and greater.
## Configuration

## Usage
Set your account email address and API key. The API key can be found on
the [My Account][my-account] page in the Cloudflare dashboard.

### Creating a Client
[my-account]: https://www.cloudflare.com/a/account

```javascript
var CFClient = require('cloudflare');
var client = new CFClient({
email: 'you@example.com',
key: 'deadbeef'
var cf = require('cloudflare')({
email: 'you@example.com',
key: 'your Cloudflare API key'
});
```

### Zones

#### `Zone`

* *API Reference*: [Zone properties](https://api.cloudflare.com/#zone-properties)

A normalized representation of a CloudFlare Zone. Properties that were
`snake_cased` have been aliased to `camelCased`. TODO: document all the known
properties.

#### `Zone.create(properties): Zone`

* properties: The properties to set on the new `Zone` object.
* *Returns*: A new `Zone` object.

Creates a new `Zone` object with the provided properties. The returned object
can be used with the below methods that accept a `Zone` object.

#### `Zone.is(z): boolean`

* z: The other object that may, or may not, be a `Zone` object.
* *Returns*: `true` if the parameter is a `Zone` object, otherwise `false`.

#### `browseZones([query, [options]]): Promise<PaginatedResponse<Zone[]>>`

* query: An object to pass filter and sorting parameters to the API
* options: *see Request Options*
* *Returns*: A Promise that resolves to a list of `Zone` objects wrapped in a `PaginatedResponse`
* *API Reference*: [List zones](https://api.cloudflare.com/#zone-list-zones)

Retrives the list of `Zone` objects, optionally filtered and sorted by `query` options.

#### `readZone(z_id, [options]): Promise<Zone>`

* z_id: The string Zone id
* options: *see Request Options*
* *Returns*: A Promise that resolves to a `Zone`
* *API Reference*: [Zone details](https://api.cloudflare.com/#zone-zone-details)

Retrives the `Zone` for the zone identifier `z_id`.

#### `editZone(z, [options]): Promise<Zone>`

* z: `Zone` object
* options: *see Request Options*
* *Returns*: A Promise that resolves to a `Zone`.
* *API Reference*: [Edit Zone Properties](https://api.cloudflare.com/#zone-edit-zone-properties)

Saves the modifications to the `Zone` object.

**Note**: The CloudFlare API currently doesn't support patching multiple
properties at once. This method executes the modifications in series, but if an
error occurs, there are no guarantees which properties would have been applied.

#### `addZone(z, [jumpstart, [options]]): Promise<Zone>`

* z: `Zone` object
* jumpstart: `true` to automatically fetch existing DNS records
(default). `false` to disable this behavior.
* options: *see Request Options*
* *API Reference*: [Create a zone](https://api.cloudflare.com/#zone-create-a-zone)

Add a zone to an account or organization.

#### `checkZoneActivation(z): Promise<{id: string}>`

* z: `Zone` object
* *API Reference*: [Initiate another zone activation check](https://api.cloudflare.com/#zone-initiate-another-zone-activation-check)

Initiate another zone activation check.

#### `deleteZone(z, [options]): Promise<{id: string}>`

* z: `Zone` object or string zone id
* options: *see Request Options*
* *Returns*: A Promise that resolves to a tombstone stub
* *API Reference*: [Delete a zone](https://api.cloudflare.com/#zone-delete-a-zone)

Deletes the `Zone` from CloudFlare. A tombstone stub is returned.

#### `deleteCache(z, query, [options]): Promise<bool>`

* z: `Zone` object or string zone id
* query: The (required) purge options for the API:
* `purge_everything`: Delete all of the zone's content from the CloudFlare
cache. **Note**: This may cause an increase in connections to your server
after performing this action.
* `files`: An array of URLs that should be removed from cache.
* `tags`: Removes assets from cache that were served with a Cache-Tag header
that matches a string in this array.
* options: *see Request Options*
* *Returns*: A Promise that resolves to `true`.
* *API Reference*:
[Purge all files](https://api.cloudflare.com/#zone-purge-all-files) and
[Purge individual files by URL and Cache-Tags](https://api.cloudflare.com/#zone-purge-individual-files-by-url-and-cache-tags)

Purges content from CloudFlare's cache. Please note that `query` is required for
this API call.

### DNS
## API Overview

The CloudFlare API client makes it easy to manage DNS records for domains on CloudFlare.
Every resource is accessed via your `cf` instance:

#### `DNSRecord`

* *API Reference*: [DNS Records for a Zone](https://api.cloudflare.com/#dns-records-for-a-zone-properties)

A normalized representation of a CloudFlare DNS Record type. Properties that
were `snake_cased` have been aliased to be `camelCased`.

#### `DNSRecord.create(properties): DNSRecord`

* properties: The properties to set on the new `DNSRecord` object.
* *Returns*: A new `DNSRecord` object.

Creates a new `DNSRecord` object with the provided properties. The returned
object can be used with the below methods that accept a `DNSRecord` object.

#### `DNSRecord.is(rr): boolean`

* rr: The other object that may, or may not, be a `DNSRecord` object.
* *Returns*: `true` if the parameter is a `DNSRecord` object, otherwise `false`.

#### `browseDNS(z, [query, [options]]): Promise<PaginatedResponse<DNSRecord[]>>`

* z: `Zone` object or string zone id
* query: An object to pass filter and sorting parameters to the API
* options: *see Request Options*
* *Returns*: A Promise that resolves to a list of `DNSRecord` objects wrapped in a `PaginatedResponse`
* *API Reference*: [List DNS Records](https://api.cloudflare.com/#dns-records-for-a-zone-list-dns-records)

Retrives the listing of `DNSRecord` objects for a `Zone` (or zone id).

#### `readDNS(dns_id, z, [options]): Promise<DNSRecord>`

* dns_id: The string DNS record id
* z: `Zone` object or string zone id
* options: *see Request Options*
* *Returns*: A Promise that resolves to a `DNSRecord`
* *API Reference*: [DNS record details](https://api.cloudflare.com/#dns-records-for-a-zone-dns-record-details)

Retrive the `DNSRecord` for an identifier `did` from `Zone` (or zone id).

#### `editDNS(d, [options]): Promise<DNSRecord>`

* d: The `DNSRecord` to be saved
* options: *see Request Options*
* *Returns*: A Promise that resolves to a new `DNSRecord`
* *API Reference*: [Update DNS record](https://api.cloudflare.com/#dns-records-for-a-zone-update-dns-record)

Save the modifications to the `DNSRecord`.

#### `addDNS(d, [options]): Promise<DNSRecord>`

* d: The `DNSRecord` to be added
* options: *see Request Options*
* *Returns*: A Promise that resolves to a new `DNSRecord`
* *API Reference*: [Create DNS record](https://api.cloudflare.com/#dns-records-for-a-zone-create-dns-record)

Create a DNS Record corresponding to the provided `DNSRecord`. A new `DNSRecord`
with an id field is returned.

#### `deleteDNS(d, [options]): Promise<{id: string}>`

* d: The `DNSRecord` to be deleted
* options: *see Request Options*
* *Returns*: A Promise that resolves to a tombstone stub
* *API Reference*: [Delete DNS record](https://api.cloudflare.com/#dns-records-for-a-zone-delete-dns-record)

Deletes the `DNSRecord` from the DNS. A tombstone stub is returned.

### CloudFlare IPs
```javascript
// cf.{ RESOURCE_NAME }.{ METHOD_NAME }
```

#### `IPRanges`
Every resource method returns a promise, which can be chained or used
with async/await.

* *API Reference*: [CloudFlare IPs properties](https://api.cloudflare.com/#cloudflare-ips-properties)
```javascript
cf.zones.read('023e105f4ecef8ad9ca31a8372d0c353').then(function (resp) {
return resp.result.status;
});

Normalized representation of the CloudFlare IP Ranges.

```
IPRanges{
IPv4CIDRs: [
'199.27.128.0/21'
],
IPv6CIDRs: [
'2400:cb00::/32'
]
// where supported
async function getZoneStatus(id) {
var resp = await cf.zones.read('023e105f4ecef8ad9ca31a8372d0c353');
return resp.result.status;
}
```

#### `IPRanges.is(ip): boolean`

* ip: The other object that may, or may not, be an `IPRanges` object.
* *Returns*: `true` if the parameter is a `IPRanges` object, otherwise `false`.

#### `readIPs(): Promise<IPRanges>`

* *Returns*: A Promise that resolves to `IPRanges`
* *API Reference*: [CloudFlare IPs](https://api.cloudflare.com/#cloudflare-ips)
### Available resources and methods

* dnsRecords
* `browse()`
* `read(dnsRecordId)`
* `edit(dnsRecordId, params)`
* `add(params)`
* `del(dnsRecordId)`
* ips
* `browse()`
* zones
* `browse()`
* `read(zoneId)`
* `edit(zoneId, params)`
* `add(params)`
* `del(zoneId)`
* `activationCheck(zoneId)`
* `purgeCache(zoneId, params)`

Retrieves the CloudFlare Edge IP addresses. These are the IP addresses used by
CloudFlare to connect to your server.
Loading

0 comments on commit 8bbdc0a

Please sign in to comment.