mirror of
https://github.com/encode/django-rest-framework.git
synced 2025-08-07 22:04:48 +03:00
Inital pass at API client docs
This commit is contained in:
parent
84bb5ea4ff
commit
63e84676a4
|
@ -204,6 +204,7 @@ The API guide is your complete reference manual to all the functionality provide
|
|||
General guides to using REST framework.
|
||||
|
||||
* [Documenting your API][documenting-your-api]
|
||||
* [API Clients][api-clients]
|
||||
* [Internationalization][internationalization]
|
||||
* [AJAX, CSRF & CORS][ajax-csrf-cors]
|
||||
* [HTML & Forms][html-and-forms]
|
||||
|
@ -324,6 +325,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|||
[settings]: api-guide/settings.md
|
||||
|
||||
[documenting-your-api]: topics/documenting-your-api.md
|
||||
[api-clients]: topics/api-clients.md
|
||||
[internationalization]: topics/internationalization.md
|
||||
[ajax-csrf-cors]: topics/ajax-csrf-cors.md
|
||||
[html-and-forms]: topics/html-and-forms.md
|
||||
|
|
164
docs/topics/api-clients.md
Normal file
164
docs/topics/api-clients.md
Normal file
|
@ -0,0 +1,164 @@
|
|||
# API Clients
|
||||
|
||||
An API client handles the underlying details of how network requests are made
|
||||
and how responses are decoded. They present the developer with an application
|
||||
interface to work against, rather than working directly with the network interface.
|
||||
|
||||
The API clients documented here are not restricted to REST framework APIs,
|
||||
and *can be used with any API that exposes a supported schema format*.
|
||||
|
||||
## Client-side Core API
|
||||
|
||||
Core API is a document specification that can be used to describe APIs. It can
|
||||
be used either server-side, as is done with REST framework's Schema generation,
|
||||
or used client-side, as described here
|
||||
|
||||
When used client-side, Core API allows for *dynamically driven client libraries*
|
||||
that can interact with any API that exposes a supported schema or hypermedia
|
||||
format.
|
||||
|
||||
Using a dynamically driven client has a number of advantages over interacting
|
||||
with an API by building HTTP requests directly.
|
||||
|
||||
#### More meaningful interaction
|
||||
|
||||
API interactions are presented in a more meaningful way. You're working at
|
||||
the application interface layer, rather than the network interface layer.
|
||||
|
||||
#### Resilience & evolvability
|
||||
|
||||
The client determines what endpoints are available, what parameters exist
|
||||
against each particular endpoint, and how HTTP requests are formed.
|
||||
|
||||
This also allows for a degree of API evolvability. URLs can be modified
|
||||
without breaking existing clients, or more efficient encodings can be used
|
||||
on-the-wire, with clients transparently upgrading.
|
||||
|
||||
#### Self-descriptive APIs
|
||||
|
||||
A dynamically driven client is able to present documentation on the API to the
|
||||
end user. This documentation allows the user to discover the available endpoints
|
||||
and parameters, and better understand the API they are working with.
|
||||
|
||||
Because this documentation is driven by the API schema it will always be fully
|
||||
up to date with the most recently deployed version of the service.
|
||||
|
||||
---
|
||||
|
||||
# Command line client
|
||||
|
||||
The command line client allows you to inspect and interact with any API that
|
||||
exposes a supported schema format.
|
||||
|
||||
## Getting started
|
||||
|
||||
To install the Core API command line client, use pip.
|
||||
|
||||
pip install coreapi
|
||||
|
||||
**TODO**
|
||||
|
||||
coreapi get http://api.example.org/
|
||||
|
||||
To interact with the API, use the `action` command. This command requires a list
|
||||
of keys that are used to index into the link.
|
||||
|
||||
coreapi action users list
|
||||
|
||||
Some actions may include optional or required parameters.
|
||||
|
||||
coreapi action users create --params username example
|
||||
|
||||
To inspect the underlying HTTP request and response, use the `--debug` flag.
|
||||
|
||||
coreapi action users create --params username example --debug
|
||||
|
||||
To see some brief documentation on a particular link, use the `describe` command,
|
||||
passing a list of keys that index into the link.
|
||||
|
||||
coreapi describe users create
|
||||
|
||||
**TODO**:
|
||||
|
||||
* string params / data params
|
||||
* file uploads
|
||||
* file downloads
|
||||
|
||||
## Authentication & headers
|
||||
|
||||
The `credentials` command is used to manage the request `Authentication:` header.
|
||||
Any credentials added are always linked to a particular domain, so as to ensure
|
||||
that credentials are not leaked across differing APIs.
|
||||
|
||||
The format for adding a new credential is:
|
||||
|
||||
coreapi credentials add <domain> <credentials string>
|
||||
|
||||
For instance:
|
||||
|
||||
coreapi credentials add api.example.org "Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
|
||||
|
||||
The optional `--auth` flag also allows you to add specific types of authentication,
|
||||
handling the encoding for you. Currently only `"basic"` is supported as an option here.
|
||||
For example:
|
||||
|
||||
coreapi credentials add api.example.org tomchristie:foobar --auth basic
|
||||
|
||||
You can also add specific request headers, using the `headers` command:
|
||||
|
||||
coreapi headers add api.example.org x-api-version 2
|
||||
|
||||
For more information and a listing of the available subcommands use `coreapi
|
||||
credentials --help` or `coreapi headers --help`.
|
||||
|
||||
## Utilities
|
||||
|
||||
The command line client includes functionality for bookmarking API URLs
|
||||
under a memorable name. For example, you can add a bookmark for the
|
||||
existing API, like so...
|
||||
|
||||
coreapi bookmarks add accountmanagement
|
||||
|
||||
There is also functionality for navigating forward or backward through the
|
||||
history of which API URLs have been accessed.
|
||||
|
||||
For more information and a listing of the available subcommands use
|
||||
`coreapi bookmarks --help` or `coreapi history --help`.
|
||||
|
||||
## Other commands
|
||||
|
||||
**TODO**
|
||||
|
||||
To display the current `Document`, use the `show` command.
|
||||
|
||||
coreapi show
|
||||
|
||||
To reload the current `Document` from the network, use `reload`.
|
||||
|
||||
coreapi reload
|
||||
|
||||
|
||||
load
|
||||
|
||||
To remove the current document, history, credentials, headers and bookmarks, use `clear`:
|
||||
|
||||
coreapi clear
|
||||
|
||||
---
|
||||
|
||||
# Python client library
|
||||
|
||||
The `coreapi` Python package allows you to programatically interact with any
|
||||
API that exposes a supported schema format.
|
||||
|
||||
## Getting started
|
||||
|
||||
client = coreapi.Client()
|
||||
schema = client.get('http://...')
|
||||
|
||||
client.action(schema, ['users', 'list'])
|
||||
client.action(schema, ['users', 'list'], params={"page": 2})
|
||||
|
||||
## Codecs
|
||||
|
||||
## Transports
|
|
@ -51,6 +51,7 @@ pages:
|
|||
- 'Settings': 'api-guide/settings.md'
|
||||
- Topics:
|
||||
- 'Documenting your API': 'topics/documenting-your-api.md'
|
||||
- 'API Clients': 'topics/api-clients.md'
|
||||
- 'Internationalization': 'topics/internationalization.md'
|
||||
- 'AJAX, CSRF & CORS': 'topics/ajax-csrf-cors.md'
|
||||
- 'HTML & Forms': 'topics/html-and-forms.md'
|
||||
|
|
Loading…
Reference in New Issue
Block a user