API (vii) Schemas & Client Libraries

A pattern is a machine-readable document that describes the available API endpoints, their URLs, and the operations they support.

Patterns can be useful tools for automatically generating documents, or they can be used to drive dynamic client libraries that can interact with the API.

Core API

Use the core API to provide a schema that supports the rest framework.

The Core API is the documentation specification used to describe the API. It is used to provide an internal representation of the available endpoints and possible interactions with the API exposure. It can be used on either the server side or the client.

When using the server side, the Core API allows the API to support rendering in various modes or hypermedia formats.

When used Client-side, the Core API allows for dynamically driven client libraries the can interact with any API that exposes A supported schema or hypermedia format.

Adding a schema

The rest framework supports clearly defined schema views or automatically generated schemas. Since we are using viewsets and routers, we can only use the automatic schema generation.

You need to coreapi install the Python package to include the API schema.

Pip Install Coreapi

Now we can add a schema to the API by including an automatically generated Schema view in the URL configuration.

From rest_framework.schemas Import Get_schema_viewschema_view = Get_schema_view (title= ' Pastebin API ') urlpatterns = [    URL (r ' ^schema/$ ', Schema_view),    ...]

If you access the API root endpoint in your browser, you should now see that corejson the presentation layer becomes an available option.

We can also request schema Accept header from the command line by specifying the desired content type in.

$ http http://127.0.0.1:8000/schema/Accept:application/coreapi+jsonHTTP/1.0 okallow:get, HEAD, optionscontent-type:application/coreapi+json{    "_meta": {        "title": "Pastebin API"    }, "    _type": " Document ",    ...

The default output style is encoded using the core JSON.

Other schema formats, such as the Open API (formerly known as Swagger), are also supported.

Using a command line client

Now that our API exposes a schema endpoint, we can use a dynamic client library to interact with the API. To demonstrate this, let's use the Core API command-line client.

The command line client can coreapi-cli be used as a package:

$ pip Install Coreapi-cli

Now check that it is available on the command line ...

$ COREAPIUSAGE:COREAPI [OPTIONS] COMMAND [ARGS]  ... Command line Client for interacting with COREAPI services.  Visit http://www.coreapi.org for more information. Options:  --version  Display the package version number.  --help     Show This message and Exit.commands: ...

First, we'll use the command line client to load the API schema.

$ coreapi Get http://127.0.0.1:8000/schema/<Pastebin API "http://127.0.0.1:8000/schema/" >    snippets: {        Highlight (ID)        list ()        read (ID)    }    users: {        list ()        read (ID)    }

We don't have authentication yet, so now we can only see the read-only endpoint, which is consistent with the API permissions we've set.

We tried to list the existing code snippets using the command line client:

$ COREAPI Action Snippets list[    {        "url": "http://127.0.0.1:8000/snippets/1/",        "id": 1,        "highlight ":" http://127.0.0.1:8000/snippets/1/highlight/",        " owner ":" Lucy ",        " title ":" Example ",        " code ":" Print (' Hello, world! ') ",        " Linenos ": True,        " language ":" Python ",        " style ":" Friendly "    },    ...

Some API endpoints require named parameters. For example, to get the high-brightness HTML for a particular snippet, we need to provide an ID.

$ COREAPI Action Snippets Highlight--param id=1<! DOCTYPE HTML PUBLIC "-//w3c//dtd HTML 4.01//en" "HTTP://WWW.W3.ORG/TR/HTML4/STRICT.DTD" >
Authenticating our Client
If we want to create, edit, and delete code snippets, we need to authenticate as valid users. In this case, we only need to use the basic auth.
Be sure to replace the following and with your actual user name and password <username> <password> .
$ COREAPI Credentials Add 127.0.0.1 <username>:<password>--auth basicadded credentials127.0.0.1 "Basic < ...> "
Now, if we get the schema again, we can see a complete set of available interactions.
$ coreapi reloadpastebin API "http://127.0.0.1:8000/schema/" >    snippets: {        Create (code, [title], [Linenos], [Language], [style])        Delete (ID)        Highlight (ID)        list ()        partial_update (ID, [title], [code], [Linenos] , [language], [style])        read (ID)        Update (ID, code, [title], [Linenos], [language], [style])    }    users: { C10/>list ()        read (ID)    }
We can now interact with these endpoints. For example, to create a new code snippet:
$ COREAPI Action Snippets Create--param title= "Example"--param code= "print (' Hello, World ')" {    "url": "// 127.0.0.1:8000/snippets/7/",    " id ": 7,    " highlight ":" http://127.0.0.1:8000/snippets/7/highlight/",    "owner": "Lucy",    "title": "Example",    "code": "Print (' Hello, World ')", "    Linenos": false,    " Language ":" Python ",    " style ":" Friendly "}
and delete the fragment:
$ coreapi Action Snippets Delete--param id=7
In addition to the command-line client, developers can also use the client library to interact with the API. The Python client library is the first available, and a JavaScript client library is scheduled to be released shortly.
For more details on customizing pattern generation and using the core API client library, you need to refer to the complete documentation.
API (vii) Schemas & Client Libraries