Я проделал большую работу вручную и часто собирал машиночитаемую спецификацию OpenAPI в рамках работы над стеком API. Создание пригодного для использования определения API — это большая работа, что делает его довольно ценным товаром, в отличие от моего твердого мнения, что сегодня они должны быть легко доступны для КАЖДОГО API.

Хотя впереди еще ОГРОМНЫЙ ОБЪЕМ работы, я чувствую, что дело начинает двигаться вперед, когда дело доходит до количества общедоступных определений API.

Чтобы экономика API работала в том масштабе, который мы все рисуем в своей голове, необходимо определить площадь ВСЕХ API и поддерживающих их операций и сделать их доступными для потребителей и поставщиков услуг. Каждый API должен иметь OpenAPI Spec, API Blueprint и Postman Collection, доступные для использования потребителями. Когда мы закрываем 2015 год, я рад сообщить, что с оптимизмом смотрю на ряд работ, которые другие в космосе вкладывают в определения API, например, люди из API Guru, которые открывают, улучшают и проверяют определения API. в различных форматах, все доступно на Github.

На разработку этих определений уходит много работы, и приятно видеть, что они вкладывают средства в эту область. Их ценный индекс из почти 200 определений API используется для поддержки любого API и дополнен индексом JSON для коллекции API. Следите за ним, так как он растет с каждым днем ​​— я знаю, что буду внимательно следить за каждой фиксацией в открытом репозитории определений API. Когда я просматриваю их коллекцию, у меня уже есть много API, но есть много других, которые я хотел бы использовать на основе работы, проделанной API Guru, — точно так же, как я призываю других делать это с моей работой стека API.

Все это заставляет меня задуматься: по мере того, как этот новый уровень определения API экономики API развивается, и мы все заимствуем, повторно используем и развиваем работу других, при чем здесь атрибуция дизайна API? В мире дел об авторском праве API после Oracle против Google, где API защищены авторским правом, как нам начать двигаться вперед с более здоровым видением определения и совместного использования проектов API, бросая вызов антиутопическому будущему, переданному нам Oracle и нашими федеральными судами. Атрибуция дизайна API — это то, как мы это делаем, когда мы отдаем должное источникам ценных определений API.

Просматривая машиночитаемый индекс коллекции APIs Guru, я заметил, что у них есть коллекция x-origin, доступная для каждого API, который они определяют. В этом объекте они описывают формат, URL-адрес и версию для файла OpenAPI Spec в доступном индексе, так же, как я делаю с «индексами APIs.json API. Я предоставил ссылки на swagger-original как часть некоторых моих индексов APIs.json, но многие из них были созданы вручную, поэтому не было источника, и в качестве источника выступала только статическая документация.

Подход API Guru заставил меня расширить свои собственные мысли по этому поводу, где я хочу разместить потенциальный источник для любого определения API в своих коллекциях. для любого определения API, которое у меня есть в моей коллекции (коллекциях). Если у определения API есть авторитетный источник, я хочу, чтобы URL-адрес был проиндексирован. Если определение API было улучшено или дополнено благодаря работе других, я хочу, чтобы эти URL-адреса были проиндексированы.Короче говоря, мне нужно указать несколько источников, а не только происхождение, как это делает APIs Guru.

Я могу собрать 5–10 отдельных спецификаций OpenAPI для любого имеющегося у меня API в поисках любых деталей, которых у меня нет ни в одном из моих собственных определений API — каждый из этих источников, если они вносят вклад, добавляют или дополняют X, составляют мои определения API, они должны быть процитированы. Я просто не думаю, что должен быть один авторитетный источник для любых определений API в мире, где иногда потребители API лучше описывают API, от которых они зависят, чем владельцы API. Я хочу указать один или несколько источников для любого определения API, которое я создаю.

Этот процесс не останавливается на существующих API, я также должен иметь возможность приписывать проекты API других. Если я заимствую дизайн Twilio и дизайнов API SendGrid (что я должен делать без юридических проблем), для своих собственных пользовательских API обмена сообщениями, я должен быть в состоянии отнести их к моему вдохновению в моих определениях API. Дизайн API будет очень похож на музыку, в том смысле, что мы будем основываться на риффах и битах друг друга, и мы должны проявлять уважение там, где это имеет смысл.

Я поиграю с потенциальной схемой объекта для моего видения атрибуции API. Опираясь на то, что делает APIs Guru со своим x-origin. Во-первых, я превращу его в коллекцию, чтобы иметь возможность ссылаться на несколько источников, затем я выйду за рамки простого происхождения и назову свой объект x-атрибуцией и добавлю свойство для определения типа атрибуции. А пока я добавлю атрибуцию в качестве строительного блока для моего Исследования определений API, которое я буду быстро расширять в отдельную категорию и, возможно, скоро приступлю к созданию реальной схемы.

Первоначально опубликовано на blog.apiware.io.