From c565029962be8f812555c6f9d782a5053e0e3942 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 26 Apr 2017 22:45:33 +0100 Subject: docs: Split API docs into their own section Third time lucky. There are two changes: - Add a new 'clients' section to the usage doc, allowing us to remove a lot of the API nitty gritty stuff from the users guide. This makes more sense as users don't really care what API method they're using - only what application). - Change the API docs from the developers guide into a quick start section, allowing us to greatly expand the REST API docs to include information on pagination, authentication, etc. Signed-off-by: Stephen Finucane --- docs/development/api.rst | 10 +++++++ docs/development/rest.rst | 67 --------------------------------------------- docs/development/xmlrpc.rst | 53 ----------------------------------- 3 files changed, 10 insertions(+), 120 deletions(-) create mode 100644 docs/development/api.rst delete mode 100644 docs/development/rest.rst delete mode 100644 docs/development/xmlrpc.rst (limited to 'docs/development') diff --git a/docs/development/api.rst b/docs/development/api.rst new file mode 100644 index 0000000..3cfefdb --- /dev/null +++ b/docs/development/api.rst @@ -0,0 +1,10 @@ +Using the APIs +============== + +Patchwork provides two APIs: the legacy :doc:`XML-RPC API <../api/xmlrpc>` and +the :doc:`REST API <../api/rest>`. You can use these APIs to interact with +Patchwork programmatically and to develop your own clients. + +For quick usage examples of the APIs, refer to the :ref:`documentation +`. For examples of existing clients, refer to +:doc:`../usage/clients`. diff --git a/docs/development/rest.rst b/docs/development/rest.rst deleted file mode 100644 index efab9f4..0000000 --- a/docs/development/rest.rst +++ /dev/null @@ -1,67 +0,0 @@ -The REST API -============ - -Patchwork provides a REST API. This API can be used to retrieve and modify -information about patches, projects and more. - -This guide covers development information for the Patchwork REST API. For -information on using the REST API, refer to `rest`. For information on general -usage of the REST API, refer to :doc:`../usage/rest`. - -.. versionadded:: 2.0 - - The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork - versions should instead refer to :doc:`xmlrpc`. - -Documentation -------------- - -Patchwork provides automatically generated documentation for the REST API. -You can find this at the following URL: - - http://patchwork.example.com/api/ - -where `patchwork.example.com` refers to the URL of your Patchwork instance. - -Interacting with the API ------------------------- - -REST APIs run over plain HTTP(S), thus, the API can be interfaced using -applications or libraries that support this widespread protocol. One such -application is `curl`__, which can be used to both retrieve and send -information to the REST API. For example, to get the version of the REST API -for a Patchwork instance hosted at `patchwork.example.com`, run: - -.. code-block:: shell - - $ curl -s http://localhost:8000/api/1.0/ | python -m json.tool - { - "patches": "http://localhost:8000/api/1.0/patches/", - "people": "http://localhost:8000/api/1.0/people/", - "projects": "http://localhost:8000/api/1.0/projects/", - "users": "http://localhost:8000/api/1.0/users/" - } - -In addition, a huge variety of libraries are available for interacting with and -parsing the output of REST APIs. The `requests`__ library is wide-spread and -well-supported. To repeat the above example using `requests`: - -.. code-block:: pycon - - $ python - >>> import json - >>> import requests - >>> r = requests.get('http://patchwork.example.com/api/1.0/') - >>> print(json.dumps(r.json(), indent=2)) - { - "users": "http://localhost:8000/api/1.0/users/", - "patches": "http://localhost:8000/api/1.0/patches/", - "projects": "http://localhost:8000/api/1.0/projects/", - "people": "http://localhost:8000/api/1.0/people/" - } - -Tools like `curl` and libraries like `requests` can be used to build anything -from small utilities to full-fledged clients targeting the REST API. - -__ https://curl.haxx.se/ -__ http://docs.python-requests.org/en/master/ diff --git a/docs/development/xmlrpc.rst b/docs/development/xmlrpc.rst deleted file mode 100644 index 4b2651f..0000000 --- a/docs/development/xmlrpc.rst +++ /dev/null @@ -1,53 +0,0 @@ -The XML-RPC API -=============== - -Patchwork provides an XML-RPC API. This API can be used to be used to retrieve -and modify information about patches, projects and more. - -This guide covers development information for the Patchwork XML-RPC API. For -information on using the REST API, refer to `rest`. For information on general -usage of the XML-RPC API, refer to :doc:`../usage/xmlrpc`. - -Documentation -------------- - -Patchwork provides automatically generated documentation for the XML-RPC API. -You can find this at the following URL: - - http://patchwork.example.com/xmlrpc/ - -where `patchwork.example.com` refers to the URL of your Patchwork instance. - -.. versionchanged:: 1.1 - - Automatic documentation generation for the Patchwork API was introduced in - Patchwork v1.1. Prior versions of Patchwork do not offer this functionality. - -Interacting with the API ------------------------- - -The Patchwork XML-RPC API provides a number of "methods". Some methods require -authentication (via HTTP Basic Auth) while others do not. Authentication uses -your Patchwork account and the on-server documentation will indicate where it -is necessary. We will only cover the unauthenticated method here for brevity - -consult the `xmlrpclib`__ documentation for more detailed examples: - -To interact with the Patchwork XML-RPC API, a XML-RPC library should be used. -Python provides such a library - `xmlrpclib` - in its standard library. For -example, to get the version of the XML-RPC API for a Patchwork instance hosted -at `patchwork.example.com`, run: - -.. code-block:: pycon - - $ python - >>> import xmlrpclib # or 'xmlrpc.client' for Python 3 - >>> rpc = xmlrpclib.ServerProxy('http://patchwork.example.com/xmlrpc/') - >>> rpc.pw_rpc_version() - 1.1 - -Once connected, the `rpc` object will be populated with a list of available -functions (or procedures, in RPC terminology). In the above example, we used -the `pw_rpc_version` method, however, it should be possible to use all the -methods listed in the server documentation. - -__ https://docs.python.org/2/library/xmlrpclib.html -- cgit v1.2.3