New REST API Yandex.Disk and Polygon. And also why is Disk another API and how we did it
Many people know that Disk already has a WebDAV API for quite some time. It is quite narrowly tailored to work with the file structure, and its implementation on different platforms often has non-critical, but not very pleasant flaws. Therefore, in addition to WebDAV, we run the REST API, which will allow developers to do the same and a little more.
For example, when using a new API, all applications that just need to store their files in the Disk will be able to access only their folder in the Users folder in the Applications folder. In the WebDAV API, the service will have to get the user permission to write / read the entire Disk, and not just a specific folder.
')
In this post, I want to talk not about the structure or operations that our API can perform - everything is pretty obvious - but I’ll go straight to interesting things: what is Hypermedia and Machine-readable and Self-describing API, and how we all implemented it .
We have provided our API with hyperlinks that link its resources to each other. They allow you to turn the client's work from jerking hard-coded URLs into navigating the links that the API provides in the body of the returned objects. We took the HAL standard as one of the simplest and most mature standards in this area. Currently, HAL has a draft RFC standard, and it can already be found in the API of some large companies.
Thanks to the support of the HAL, the client understands what can be done with each object, knows the prepared or template-based RFC 6570 URL and the HTTP action method. In turn, client application developers can write less code, spending less time on it, and this code becomes easier and easier to read. For example, a code that performs basic operations with folders in a disk that does not use hyperlinks would look something like this:
When using hyperlinks, there is no need to manually collect URLs and worry about query parameters already known to the object on which the operation is performed:
In addition to hypermedia, we decided to make our API self-describing and machine-readable. In the process of preparation, we studied various standards for describing REST APIs, such as RAML, WADL, JSON Schema + JSON HyperSchema, IO Docs, Apiary Blueprints, but the final choice fell on Swagger. One of the main advantages of Swagger is that it is being developed as a standard (the Yandex.Disk API supports version 1.2 of the specification, but the standard version 2.0 is being developed). It describes the REST API using JSON, is fairly simple to understand, and has a nice ecosystem of tools for working with API descriptions.
Swagger documentation covers all resources available in the API and methods for invoking them. For each resource method, there is a description of the parameters it takes and the structure of the returned objects.
This description can be used as a starting point for universal Swagger clients, as well as for autogenerating parts of the code of native SDKs for various languages.
Thanks to the Swagger API documentation, we launched the Polygon project, which gives developers the opportunity, without writing a single line of code, to send combat requests to the API. In addition, Polygon can serve as an example of a universal client for any API that supports the Swagger description. Our developer Roma Akinfeev prepared a screencast in which he talked a little about the possibilities of Polygon.
Now, the Disk API functionality is more than enough to develop applications that work with user content, for example, photo editors, slide show generators, media players, etc.
Using our API, you can store and synchronize application data between user devices, for example, save progress in games or store user favorites and bookmarks created in your application.
We tried to make the new API of the Disk such that it was easy and pleasant for you to use it, studying the documentation less and more intuitively learning it in practice. Therefore, without further ado, we suggest using the Site and discover the new REST API of Yandex.Disk yourself.
For example, when using a new API, all applications that just need to store their files in the Disk will be able to access only their folder in the Users folder in the Applications folder. In the WebDAV API, the service will have to get the user permission to write / read the entire Disk, and not just a specific folder.
')
In this post, I want to talk not about the structure or operations that our API can perform - everything is pretty obvious - but I’ll go straight to interesting things: what is Hypermedia and Machine-readable and Self-describing API, and how we all implemented it .
Hypermedia API
We have provided our API with hyperlinks that link its resources to each other. They allow you to turn the client's work from jerking hard-coded URLs into navigating the links that the API provides in the body of the returned objects. We took the HAL standard as one of the simplest and most mature standards in this area. Currently, HAL has a draft RFC standard, and it can already be found in the API of some large companies.
Thanks to the support of the HAL, the client understands what can be done with each object, knows the prepared or template-based RFC 6570 URL and the HTTP action method. In turn, client application developers can write less code, spending less time on it, and this code becomes easier and easier to read. For example, a code that performs basic operations with folders in a disk that does not use hyperlinks would look something like this:
Hidden text
# -*- coding: utf-8 -*- import urllib import httplib import json import uritemplate headers = {'Authorization': '<OAuth >'} connection = httplib.HTTPSConnection('cloud-api.yandex.net') resource_url = '/v1/disk/resources' def request(method, url, query=None): if query: qs = urllib.urlencode(query) url = '%s?%s' % (url, qs) connection.request(method, url, headers=headers) resp = connection.getresponse() content = resp.read() obj = json.loads(content) if content else None status = resp.status if status == 201: # obj = request(obj['method'], obj['href']) return obj if __name__ == '__main__': # path = '/foo' folder = request('PUT', resource_url, {'path': path}) # new_path = '/bar' folder = request('POST', '%s/move' % resource_url, {'path': new_path, 'from': path}) # copy_path = '/foobar' folder_copy = request('POST', '%s/copy' % resource_url, {'path': copy_path, 'from': new_path}) # request('DELETE', resource_url, {'path': new_path}) request('DELETE', resource_url, {'path': copy_path}) When using hyperlinks, there is no need to manually collect URLs and worry about query parameters already known to the object on which the operation is performed:
Hidden text
# -*- coding: utf-8 -*- import urllib import httplib import json import uritemplate headers = {'Authorization': '<OAuth >', 'Accept': 'application/hal+json'} connection = httplib.HTTPSConnection('cloud-api.yandex.net') resource_url = '/v1/disk/resources?path={path}' def request(method, url, params=None): url = uritemplate.expand(url, params or {}) connection.request(method, url, headers=headers) resp = connection.getresponse() content = resp.read() obj = json.loads(content) if content else None status = resp.status if status == 201: # status, obj = request(obj['method'], obj['href']) return status, obj def do(resource, action, params=None): link = resource['_links'][action] _, obj = request(link['method'], link['href'], params) return obj if __name__ == '__main__': # _, folder = request('PUT', uritemplate.expand(resource_url, {'path': '/foo'})) # folder = do(folder, 'move', {'path': '/bar'}) # folder_copy = do(folder, 'copy', {'path': '/foobar'}) # do(folder, 'delete') do(folder_copy, 'delete') Machine-readable & Self-describing API
In addition to hypermedia, we decided to make our API self-describing and machine-readable. In the process of preparation, we studied various standards for describing REST APIs, such as RAML, WADL, JSON Schema + JSON HyperSchema, IO Docs, Apiary Blueprints, but the final choice fell on Swagger. One of the main advantages of Swagger is that it is being developed as a standard (the Yandex.Disk API supports version 1.2 of the specification, but the standard version 2.0 is being developed). It describes the REST API using JSON, is fairly simple to understand, and has a nice ecosystem of tools for working with API descriptions.
Swagger documentation covers all resources available in the API and methods for invoking them. For each resource method, there is a description of the parameters it takes and the structure of the returned objects.
This description can be used as a starting point for universal Swagger clients, as well as for autogenerating parts of the code of native SDKs for various languages.
Polygon
Thanks to the Swagger API documentation, we launched the Polygon project, which gives developers the opportunity, without writing a single line of code, to send combat requests to the API. In addition, Polygon can serve as an example of a universal client for any API that supports the Swagger description. Our developer Roma Akinfeev prepared a screencast in which he talked a little about the possibilities of Polygon.
More apps are good and different!
Now, the Disk API functionality is more than enough to develop applications that work with user content, for example, photo editors, slide show generators, media players, etc.
Using our API, you can store and synchronize application data between user devices, for example, save progress in games or store user favorites and bookmarks created in your application.
We tried to make the new API of the Disk such that it was easy and pleasant for you to use it, studying the documentation less and more intuitively learning it in practice. Therefore, without further ado, we suggest using the Site and discover the new REST API of Yandex.Disk yourself.
Source: https://habr.com/ru/post/227377/
All Articles