Как изобразить мэппинг (маппинг, mapping) данных в разных системах (источниках)
В этом посте под мэппингом понимается это соотношение между данными, которые находятся в разных системах.
Как техпису описать мэппинг данных? Хороший и понятный большинству способ — отобразить процесс визуально.
На скрине — простой пример, как это может выглядеть.
Согласитесь, здесь все предельно понятно: что откуда берется в одной системе и куда сохраняется в другой, как при этом преобразуются данные (если есть преобразование).
А какими инструментами можно это делать?
Вариантов масса. Хочешь — рисуй руками. А хочешь — кодом. Мне ближе второй вариант. Про него расскажу в одном из следующих постов.
В этом посте под мэппингом понимается это соотношение между данными, которые находятся в разных системах.
Как техпису описать мэппинг данных? Хороший и понятный большинству способ — отобразить процесс визуально.
На скрине — простой пример, как это может выглядеть.
Согласитесь, здесь все предельно понятно: что откуда берется в одной системе и куда сохраняется в другой, как при этом преобразуются данные (если есть преобразование).
А какими инструментами можно это делать?
Вариантов масса. Хочешь — рисуй руками. А хочешь — кодом. Мне ближе второй вариант. Про него расскажу в одном из следующих постов.
👍6🔥4
НЛО прилетело, приглашение принесло
Решил я на днях побороть вселенскую несправедливость и стать автором на Хабре.
Не порядок ведь: писал на Хабр не раз, но было это всё для клиентов, а публикаций от своего имени не было (хотя зарегался там в 2016 году).
И вот свершилось. Пару дней дней назад добавил на Хабр статью по материалам моего доклада на TW Days#1, а сегодня после обеда ее выпустили из песочницы.
Вот, собственно, статья.
Теперь я официально «Захабренный» (только бы не заминусовали новичка ).
Решил я на днях побороть вселенскую несправедливость и стать автором на Хабре.
Не порядок ведь: писал на Хабр не раз, но было это всё для клиентов, а публикаций от своего имени не было (хотя зарегался там в 2016 году).
И вот свершилось. Пару дней дней назад добавил на Хабр статью по материалам моего доклада на TW Days#1, а сегодня после обеда ее выпустили из песочницы.
Вот, собственно, статья.
Теперь я официально «Захабренный» (
Хабр
Документирование HTTP API (и не только) с Foliant
Привет, Хабр. В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь...
🔥15❤3😁1
Регулярки можно изображать в виде схем
И делается все без особых напрягов.
Вы знали об этом? Я — нет. И только недавно узнал.
А ведь очень удобно.
И готовый инструмент для такой задачи есть. Это — PlantUML.
Скармливаем ему регулярное выражение и получаем вполне себе понятую и удобоваримую схему.
Пример кода для схематического представления регулярки для проверки номера телефона, взятой отсюда (номер 3 в списке):
Результат — на картинке.
Согласитесь, довольно удобно и просто читать такую схему.
И делается все без особых напрягов.
Вы знали об этом? Я — нет. И только недавно узнал.
А ведь очень удобно.
И готовый инструмент для такой задачи есть. Это — PlantUML.
Скармливаем ему регулярное выражение и получаем вполне себе понятую и удобоваримую схему.
Пример кода для схематического представления регулярки для проверки номера телефона, взятой отсюда (номер 3 в списке):
@startregex
title RegExp для проверки номера телефона
/^\+?(\d{1,3})?[- .]?\(?(?:\d{2,3})\)?[- .]?\d\d\d[- .]?\d\d\d\d$/
@endregex
Результат — на картинке.
Согласитесь, довольно удобно и просто читать такую схему.
❤6🔥5
Про мутации (нет, это не из постапокалиптических фильмов, а из API)
Доводилось ли вам слышать про мутации?
В контексте техписательства (и не только) мутация — это тип операции в GraphQL API, с помощью которой меняются данные на сервере: добавляются, изменяются и удаляются.
Если в HTTP API (или REST, с вашего позволения) используется четыре разных типа запроса (имеется ввиду их разделение по используемому HTTP-глаголу):
-
-
-
-
то в GraphQL для этого всего есть один тип операции
А как тогда определять, что делает та или иная мутация, создает что-то, изменяет или удаляет? Нейминг!!! Важно при проектировании GraphQL API (впрочем, как и проектировании любого другого API) называть операции понятными именами.
Например:
•
•
•
Ну и прикрепляю картинку: так искусственный интеллект видит изображение на тему «Использование мутаций в GraphQL API».
Доводилось ли вам слышать про мутации?
В контексте техписательства (и не только) мутация — это тип операции в GraphQL API, с помощью которой меняются данные на сервере: добавляются, изменяются и удаляются.
Если в HTTP API (или REST, с вашего позволения) используется четыре разных типа запроса (имеется ввиду их разделение по используемому HTTP-глаголу):
-
POST,-
PUT,-
PATCH,-
DELETE.то в GraphQL для этого всего есть один тип операции
Mutation.А как тогда определять, что делает та или иная мутация, создает что-то, изменяет или удаляет? Нейминг!!! Важно при проектировании GraphQL API (впрочем, как и проектировании любого другого API) называть операции понятными именами.
Например:
•
createUser — понятно, что мутация будет создавать пользователя.•
updateProduct — очевидно, что такая мутация обновляет сведения о продукте.•
deleteFilm — видно, что мутация удаляет фильм.Ну и прикрепляю картинку: так искусственный интеллект видит изображение на тему «Использование мутаций в GraphQL API».
❤7👌2
IKIWISI: техписы тоже с этим встречаются
Есть у аналитиков аббревиатура IKIWISI, образованная от фразы, которую многие просто ненавидят. Это фраза «I’ll know it when I see it», что переводится как «Узнаю, когда увижу».
Обычно такое слышишь от заказчика, который толком не знает, чего он хочет: типа «Ты что-нибудь сделай, а том посмотрим, то ли это, что я хочу».
У техписов тоже такое случается частенько: приходит заказчик, просит сделать какой-то документ, но объяснить, что в нем должно быть, и как это должно выглядеть, не может. Так что, аббревиатура IKIWISI и нелюбовь к ней, я считаю, к техническим писателям тоже применимы. Ну и IKIWISI — это «родня» фразы «Без нормального ТЗ результат будет ХЗ».
Что скажете?
Есть у аналитиков аббревиатура IKIWISI, образованная от фразы, которую многие просто ненавидят. Это фраза «I’ll know it when I see it», что переводится как «Узнаю, когда увижу».
Обычно такое слышишь от заказчика, который толком не знает, чего он хочет: типа «Ты что-нибудь сделай, а том посмотрим, то ли это, что я хочу».
У техписов тоже такое случается частенько: приходит заказчик, просит сделать какой-то документ, но объяснить, что в нем должно быть, и как это должно выглядеть, не может. Так что, аббревиатура IKIWISI и нелюбовь к ней, я считаю, к техническим писателям тоже применимы. Ну и IKIWISI — это «родня» фразы «Без нормального ТЗ результат будет ХЗ».
Что скажете?
🤝13❤5
Умели же когда-то обложки привлекательные для книг делать
Разбирал вчера свои книжные запасы и нашел эту книгу из 2013 года.
Кстати, книга просто офигенская. После нее я вкатился в написание экспертных статей для SEO-специалистов и интернет-маркетологов. Сейчас, конечно, SEO другое, но основы основ из этой книги можно почерпнуть.
Разбирал вчера свои книжные запасы и нашел эту книгу из 2013 года.
Кстати, книга просто офигенская. После нее я вкатился в написание экспертных статей для SEO-специалистов и интернет-маркетологов. Сейчас, конечно, SEO другое, но основы основ из этой книги можно почерпнуть.
🔥6😁5
Ура!!! Я только что защитил дипломный проект!!!
8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но иподробности позже .
8 месяцев обучения пролетели незаметно. И было это продуктивно.
Теперь я не только технический писатель, но и
🔥12🏆9👍2👏1
Техпис не должен... Или рынок все порешает
Наверное, это холиварная тем, но все-таки.
Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.
У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.
Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....
А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).
Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?
Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.
Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.
Что скажете?
Наверное, это холиварная тем, но все-таки.
Что-то в последнее время все чаще стали попадаться высказывания типа «Техпис не должен...». Как правило, они всплывают в обсуждениях вакансий.
У большего количества таких высказываний посыл такой: мол техпис не должен делать ничего, кроме как писать инструкции.
Они говорят, что техпис не должен:
- описывать архитектуру,
- участвовать в написании спецификаций,
- лезть в код и разбираться с тем, чего там понаписали разработчики,
- настраивать пайплайны сборки документации,
- рисовать диаграммы за аналитиков и архитекторов....
А вот я так не считаю. Я думаю, что техпис должен. Должен стремиться к тому, чтобы пощупать всё, попробовать всё, понабивать шишки обо всё.
Должен, но с оговоркой: если работодатель достойно за это платит (достойная оплата — это тема для отдельного разговора).
Почему техпис должен? Я считаю, что это полезно для него же в первую очередь. Я уверен, что востребованный на рынке технический писатель — это T-shape специалист. А как стать таким специалистом, если ты свято веришь в «Техпис не должен»?
Водитель фуры, например тоже не должен менять колесо (для этого есть специальные бригады). Но большинство дальнобойщиков не ждет, пока к ним приедет эта самая бригада. Они берут и делают все самостоятельно.
Разработчики, по-хорошему, не должны настраивать CI/CD для своих продуктов (есть же девопсы под это дело). Но знаю, что многие сами это делают.
Да, может быть, в идеальном мире технический писатель реально не должен ничего, кроме как сидеть в уголочке и тихонько писать свои инструкции. Но живем мы в мире реальном. И я считаю, что техпис еще много чего должен (при условии получения соответствующего поощрения от работодателя). А за тех, кто «не должен» рынок все сам порешает.
Что скажете?
💯16❤3🌚1
Техписа на них нет...
Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
Увидел в лифте такие вот правила пользования.
И они мне сломали мозг. Попросил жену и детей посмотреть на это и сказать, что здесь не так.
И все трое, включая 10-летнего ребенка, указали на одну и ту же проблему (которую я тоже сразу увидел).
Как думаете, что смутило всех в этой картинке?
🤯3😱1
Долго не можете найти техписа? Возможно, вам нужно поменять рекрутера
За последний месяц я получил 16 предложений от разных компаний (работу, если что, пока не ищу, они просто сами на меня выходят).
Заметил одну вещь. Ну как заметил, я и ранее, когда занимался контентом для агентства IT-рекрутинга, об этом знал. Но думал, что сейчас все стало лучше.
А вот хрен. Ничего лучше не стало, и многие HRы и рекрутеры не хотят работать.
Почти каждому из написавших мне я задавал уточняющие вопросы по вакансии. Из 16 вакансий вопросов не возникло по 6 (там все было понятно и доходчиво расписано).
По десяти полученным предложениям были отправлены уточняющие вопросы (про вилку, стек, условия удалёнки и пр.). И только по трем была получена обратная связь. Остальные 7 HRов (или рекрутеров) просто молча отвалились. Естественно, когда они придут в следующий раз с предложениями, так же столкнутся с молчанием :) Я неверю, что они могут искать ответы на вопросы по 1-2 неделе, если что.
Вот вам и причина долгих поисков. Она на поверхности: кто-то на букву «Эйчар» или «Рекр» просто не хочет нормально работать.
Недавно в одном из каналов для бизнесменов рассматривался похожий кейс. Компания более полугода не могла найти сварщика. Когда начали разбираться, куда ж делись все сварщики, проанализировали критерии, по которым HR вела поиски (и чуть не поседели). Среди критериев там был возраст до 30 лет, амбициозность и … барабанная дробь … активность в Инсте (активность в Инсте сварщика, блеать!!!). За поиски взялся руководитель и нашел спеца за 3 дня.
Техписы, конечно, не сварщики, но подход к их поиску, как я погляжу, у некоторых примерно такой же — спустя рукава.
Удачи в поисках. И если они затянулись, бегите к HRу (рекрутеру) и смотрите, что и как он это делает.
За последний месяц я получил 16 предложений от разных компаний (работу, если что, пока не ищу, они просто сами на меня выходят).
Заметил одну вещь. Ну как заметил, я и ранее, когда занимался контентом для агентства IT-рекрутинга, об этом знал. Но думал, что сейчас все стало лучше.
А вот хрен. Ничего лучше не стало, и многие HRы и рекрутеры не хотят работать.
Почти каждому из написавших мне я задавал уточняющие вопросы по вакансии. Из 16 вакансий вопросов не возникло по 6 (там все было понятно и доходчиво расписано).
По десяти полученным предложениям были отправлены уточняющие вопросы (про вилку, стек, условия удалёнки и пр.). И только по трем была получена обратная связь. Остальные 7 HRов (или рекрутеров) просто молча отвалились. Естественно, когда они придут в следующий раз с предложениями, так же столкнутся с молчанием :) Я неверю, что они могут искать ответы на вопросы по 1-2 неделе, если что.
Вот вам и причина долгих поисков. Она на поверхности: кто-то на букву «Эйчар» или «Рекр» просто не хочет нормально работать.
Недавно в одном из каналов для бизнесменов рассматривался похожий кейс. Компания более полугода не могла найти сварщика. Когда начали разбираться, куда ж делись все сварщики, проанализировали критерии, по которым HR вела поиски (и чуть не поседели). Среди критериев там был возраст до 30 лет, амбициозность и … барабанная дробь … активность в Инсте (активность в Инсте сварщика, блеать!!!). За поиски взялся руководитель и нашел спеца за 3 дня.
Техписы, конечно, не сварщики, но подход к их поиску, как я погляжу, у некоторых примерно такой же — спустя рукава.
Удачи в поисках. И если они затянулись, бегите к HRу (рекрутеру) и смотрите, что и как он это делает.
💯11👍1
Идентификатор ресурса в API. Когда его можно назвать хорошим
Идентификаторы (далее ID) позволяют однозначно идентифицировать (простите за тавтологию) конкретный объект (или ресурс API в нашем случае). И к их формированию не стоит подходить «спустя рукава»: хотя казалось бы, что там придумывать, просто взял и пронумеровал все (нот нет, не прокатит).
В разных источниках встречается от 5 до 8 атрибутов (или признаков), за счет которых ID можно назвать хорошим. Больше всего мне понравилось, как это сформулировал Д. Гивакс.
Он выделяет следующие атрибуты хороших идентификаторов ресурсов API:
1️⃣ Уникальность.
2️⃣ Непредсказуемость.
3️⃣ Простота использования.
4️⃣ Постоянство.
5️⃣ Быстрота и легкость генерации.
6️⃣ Читабельность.
7️⃣ Информационная плотность.
Подробно эти атрибуты (если не все, то большую часть ) разберем в следующих постах. И тогда вы поймете, почему использовать в качестве ID просто цифры по порядку с единицы (или нуля) и далее — не есть хорошо, или почему в идентификаторах не рекомендуют использовать некоторые буквы, цифры и символы.
Идентификаторы (далее ID) позволяют однозначно идентифицировать (простите за тавтологию) конкретный объект (или ресурс API в нашем случае). И к их формированию не стоит подходить «спустя рукава»: хотя казалось бы, что там придумывать, просто взял и пронумеровал все (нот нет, не прокатит).
В разных источниках встречается от 5 до 8 атрибутов (или признаков), за счет которых ID можно назвать хорошим. Больше всего мне понравилось, как это сформулировал Д. Гивакс.
Он выделяет следующие атрибуты хороших идентификаторов ресурсов API:
1️⃣ Уникальность.
2️⃣ Непредсказуемость.
3️⃣ Простота использования.
4️⃣ Постоянство.
5️⃣ Быстрота и легкость генерации.
6️⃣ Читабельность.
7️⃣ Информационная плотность.
Подробно эти атрибуты (
✍4👍1
Вопрос для утра пятницы.
Метод GET в HTTP API:
Метод GET в HTTP API:
Anonymous Poll
57%
Всегда идемпотентен. Зуб даю.
43%
Ну нет же, не всегда.
❤2🔥1💩1🤡1
Кто хочет вкатиться в Docs as code? У моего коллеги в канале стартовал курс (бесплатный!!!!) для новичков.
Присоединяйтесь, Антон плохому не научит.
Присоединяйтесь, Антон плохому не научит.
🔥7
Forwarded from Parawriter
Привет!
Ну вот, закончились посты про погружение в профессию, и стало немного грустно. Может, организуем какую-нибудь новую серию тематических публикаций?
Что скажете, если мы проведём практический курс по docs-as-code? Будет весело — познакомимся с подходом «Документация как код» (в моей интерпретации), настроим инструменты и организуем настоящий процесс работы с документацией через git с последующей публикацией на сгенерированном html-сайте. Всё по-настоящему, но без трудностей и нюансов, которые встречаются на пути техписателя в реальной рабочей жизни.
Назовём этот курс как-нибудь романтично —маэстро! Docs as code для самых маленьких.
Работаем по проверенной схеме — посты курса будут публиковаться с хештегом #docsascode в хронологическом порядке и с относительно стабильной периодичностью 🙃
Право перебивать тематические публикации чем-то ещё оставляю за собой:)
Надеюсь, мы все хорошо проведём время!
P.S. Курс бесплатный, но ваши сердечки, птички, рукопожатия и даже звёздочки будут лучшей наградой!
#практика
Ну вот, закончились посты про погружение в профессию, и стало немного грустно. Может, организуем какую-нибудь новую серию тематических публикаций?
Что скажете, если мы проведём практический курс по docs-as-code? Будет весело — познакомимся с подходом «Документация как код» (в моей интерпретации), настроим инструменты и организуем настоящий процесс работы с документацией через git с последующей публикацией на сгенерированном html-сайте. Всё по-настоящему, но без трудностей и нюансов, которые встречаются на пути техписателя в реальной рабочей жизни.
Назовём этот курс как-нибудь романтично —
Работаем по проверенной схеме — посты курса будут публиковаться с хештегом #docsascode в хронологическом порядке и с относительно стабильной периодичностью 🙃
Право перебивать тематические публикации чем-то ещё оставляю за собой:)
Надеюсь, мы все хорошо проведём время!
P.S. Курс бесплатный, но ваши сердечки, птички, рукопожатия и даже звёздочки будут лучшей наградой!
#практика
🔥17
А не хотите мини-курс по документированию API?
Хочу сделать мини-курс по документированию HTTP API.
Но не совсем прям только по документированию.
Я вижу это все так:
1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит вам немного побыть в роли того, кто этим занимается, и в общих чертах понять, как это все происходит.
2. Далее мы создадим для этого API спецификацию в формате Open API. И это уже будет одним из видов документации.
3. Затем из полученной спецификации мы сгенерируем статический сайт-справочник. Для этого будем использовать Foliant. Возможно, попробуем и другие инструменты, чтобы почувствовать разницу.
4. Напишем доку вручную (как будто у нас нет Open API-спецификации) и снова генерируем сайт-справочник из всего этого.
И не хотелось бы, чтобы на этом все закончилось. Я думаю (не обещаю, но хотелось бы это реализовать), что мы замокаем API, либо развернем его с помощью специального сервиса, или же вообще сгенерируем код бэкенда и разместим все это дело где-нибудь. Потом «подергаем API-ручки», чтобы вы знали, с какой стороны подойти к API.
Как вам идея? Если этот пост наберет 30 сердечек ❤️ к исходу среды (18 сентября), мини-курсу быть, не наберет — ну и фиг с ним, с этим курсом.
Все будет происходить здесь, в этом канале.
Предложения и пожелания приветствуются: оставляйте их в комментах. И если знаете кого-то, кому это может быть интересно, приглашайте в канал.
Хочу сделать мини-курс по документированию HTTP API.
Но не совсем прям только по документированию.
Я вижу это все так:
1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит вам немного побыть в роли того, кто этим занимается, и в общих чертах понять, как это все происходит.
2. Далее мы создадим для этого API спецификацию в формате Open API. И это уже будет одним из видов документации.
3. Затем из полученной спецификации мы сгенерируем статический сайт-справочник. Для этого будем использовать Foliant. Возможно, попробуем и другие инструменты, чтобы почувствовать разницу.
4. Напишем доку вручную (как будто у нас нет Open API-спецификации) и снова генерируем сайт-справочник из всего этого.
И не хотелось бы, чтобы на этом все закончилось. Я думаю (не обещаю, но хотелось бы это реализовать), что мы замокаем API, либо развернем его с помощью специального сервиса, или же вообще сгенерируем код бэкенда и разместим все это дело где-нибудь. Потом «подергаем API-ручки», чтобы вы знали, с какой стороны подойти к API.
Как вам идея? Если этот пост наберет 30 сердечек ❤️ к исходу среды (18 сентября), мини-курсу быть, не наберет — ну и фиг с ним, с этим курсом.
Все будет происходить здесь, в этом канале.
Предложения и пожелания приветствуются: оставляйте их в комментах. И если знаете кого-то, кому это может быть интересно, приглашайте в канал.
1❤47🔥8
PRO_техписательство
А не хотите мини-курс по документированию API? Хочу сделать мини-курс по документированию HTTP API. Но не совсем прям только по документированию. Я вижу это все так: 1. Мы спроектируем свой API. Небольшой такой, буквально на несколько методов. Это позволит…
Дожидаться исхода среды не пришлось.
На утро есть 35 сердечек.
Значит, курсу быть.
В понедельник (23.09) опубликую подробности и правила.
Не теряйтесь.
На утро есть 35 сердечек.
Значит, курсу быть.
В понедельник (23.09) опубликую подробности и правила.
Не теряйтесь.
🔥10❤5
PRO_техписательство
Ура!!! Я только что защитил дипломный проект!!! 8 месяцев обучения пролетели незаметно. И было это продуктивно. Теперь я не только технический писатель, но и подробности позже .
Приехал-таки мой диплом.
Теперь официально: технический писатель системный аналитик.
Теперь официально: технический писатель системный аналитик.
🔥28
Привет, сегодня понедельник, 23.09, а значит, пора начинать наш мини-курс по проектированию API.
Итак, тренироваться будем накошках техписах.
В рамках курса мы спроектируем и задокументируем API (REST like, не побоюсь этого слова) в соответствии с ТЗ:
Цель: Разработать API для управления базой данных о технических писателях и их навыках.
Сущности, которыми будет оперировать API:
Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скилл), контактные данные.
Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Действия, которые будут реализованы в API:
- Получение списка технических писателей.
- Получение списка скиллов.
- Получение информации о техническом писателе по идентификатору.
- Получение информации о навыке.
- Добавление нового технического писателя.
- Редактирование сведений о техническом писателе.
- Удаление технического писателя.
- Добавление нового навыка.
- Редактирование навыка.
- Удаление навыка.
А теперь правила, ограничения, условия:
1. Не будем запихивать в сущности кучу полей. Наша цель все-таки — научиться документировать.
2. Не будем пытаться соблюсти все паттерны проектирования API и следовать best practices. Наша цель — см. П1.
3. Не будем описывать схему и принципы авторизации. Про цель вы в курсе :), да?
4. Не будем останавливаться на каких-то базовых вещах типа установки git на компьютер, настройки рабочего окружения и, глубокой теории по технологиям и инструментам. Но если будут возникать вопросы, будем стараться решать их вместе.
Про периодичность публикации постов. Не буду публиковать их часто: не более двух постов из курса в неделю, чтобы все смогли в нормальном темпе переваривать информацию и разбираться с возникающими вопросами.
Посты из курса буду помечать хэштегом #apidocs.
Вопросы, жалобы, предложения?
Следующий пост будет в четверг, 26.09: займемся описанием и проектированием сущностей API.
До встречи.
Итак, тренироваться будем на
В рамках курса мы спроектируем и задокументируем API (REST like, не побоюсь этого слова) в соответствии с ТЗ:
Цель: Разработать API для управления базой данных о технических писателях и их навыках.
Сущности, которыми будет оперировать API:
Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скилл), контактные данные.
Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Действия, которые будут реализованы в API:
- Получение списка технических писателей.
- Получение списка скиллов.
- Получение информации о техническом писателе по идентификатору.
- Получение информации о навыке.
- Добавление нового технического писателя.
- Редактирование сведений о техническом писателе.
- Удаление технического писателя.
- Добавление нового навыка.
- Редактирование навыка.
- Удаление навыка.
А теперь правила, ограничения, условия:
1. Не будем запихивать в сущности кучу полей. Наша цель все-таки — научиться документировать.
2. Не будем пытаться соблюсти все паттерны проектирования API и следовать best practices. Наша цель — см. П1.
3. Не будем описывать схему и принципы авторизации. Про цель вы в курсе :), да?
4. Не будем останавливаться на каких-то базовых вещах типа установки git на компьютер, настройки рабочего окружения и, глубокой теории по технологиям и инструментам. Но если будут возникать вопросы, будем стараться решать их вместе.
Про периодичность публикации постов. Не буду публиковать их часто: не более двух постов из курса в неделю, чтобы все смогли в нормальном темпе переваривать информацию и разбираться с возникающими вопросами.
Посты из курса буду помечать хэштегом #apidocs.
Вопросы, жалобы, предложения?
Следующий пост будет в четверг, 26.09: займемся описанием и проектированием сущностей API.
До встречи.
👍16🔥11❤2
#apidocs
Привет. Продолжаем курс по документированию API.
Сегодня займемся проектированием ресурсов (сущностей).
Если кратко, ресурс в API — это сущность, с которой можно взаимодействовать через API. В нашем API это — «Технический писатель» и «Навык»
Ранее мы определили, что будем работать со следующими ресурсами:
- Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скиллов), контактные данные.
- Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Для проектирования можно использовать таблицы (это удобно, согласитесь?).
Спроектируем ресурс «Технический писатель»:
Структура ресурса:
Что здесь нужно пояснить:
1. Запомните, что ресурс в API — это не то же самое, что хранится в базе данных (проектирование БД — отдельный разговор). Т.е. одна сущность, которой мы оперируем в API, может как матрешка собираться из нескольких таблиц.
2. Тип данных для id в нашем случае — целое число. Но часто используют строковый формат: все из-за простоты его сериализации (если интересно можно углубиться в особенности работы сданными в разных языках). При это, если в API id — строка, это не значит, что в базе данных он тоже хранится в виде строки.
3. Для типа данных string в спецификации еще можно указать формат. Об этом — в следующих уроках.
4. Список скиллов в ресурсе — это массив идентификаторов скиллов. Можно их указать и в другом виде, например в виде массива объектов, или ссылок. В любом случае, чтобы, например, все вывести на фронте (информацию про нашего техписа и про его скиллы, «под капотом» будет «дергаться» не один метод).
5. Контактные данные можно представить в виде массива с разными полями (телефон, сайт, канал в Телеграм и пр.). Но не будет усложнять. Пусть у нас будет 2 отдельных поля, одно из которых должно будет заполнено обязательно при добавлении в базу нового техписа.
По аналогии спроектируем ресурс «Навык»:
Что здесь нужно пояснить:
1. Поле «Подтверждающий документ» с типом string. В нашем случае это будет ссылка на изображение диплома, сертификата и пр.
2. Поле «Ссылки на примеры» с типом array(string). В нашем случае это будет массив со ссылками на примеры работ по данному навыку.
Что дальше? А дальше, имея представление о ресурсах и перечень действий, которые можно будет с ними выполнить, можно приступать к подготовке OpenAPI спецификации для нашего API.
Этим займемся в следующий раз.
А перед этим рекомендую ознакомиться с OpenAPI Specification v3.1.0 (хотя бы вскользь).
Привет. Продолжаем курс по документированию API.
Сегодня займемся проектированием ресурсов (сущностей).
Если кратко, ресурс в API — это сущность, с которой можно взаимодействовать через API. В нашем API это — «Технический писатель» и «Навык»
Ранее мы определили, что будем работать со следующими ресурсами:
- Технический писатель. Поля: ID, имя, отчество, фамилия, опыт работы, список навыков (скиллов), контактные данные.
- Навык: ID, название навыка, алиас, описание навыка, подтверждающий документ, ссылки на примеры.
Для проектирования можно использовать таблицы (это удобно, согласитесь?).
Спроектируем ресурс «Технический писатель»:
Структура ресурса:
|Название поля|Имя поля в API|Тип данных|
|-------------|--------------|----------|
|Идентификатор|id|integer|
|Фамилия|secondName|string|
|Имя|firstName|string|
|Отчество|patronymic|string|
|Опыт работы|experience|integer|
|Список скиллов|skills|array(integer)|
|Телефон|phone|string|
|Электронная почта|email|string|
Что здесь нужно пояснить:
1. Запомните, что ресурс в API — это не то же самое, что хранится в базе данных (проектирование БД — отдельный разговор). Т.е. одна сущность, которой мы оперируем в API, может как матрешка собираться из нескольких таблиц.
2. Тип данных для id в нашем случае — целое число. Но часто используют строковый формат: все из-за простоты его сериализации (если интересно можно углубиться в особенности работы сданными в разных языках). При это, если в API id — строка, это не значит, что в базе данных он тоже хранится в виде строки.
3. Для типа данных string в спецификации еще можно указать формат. Об этом — в следующих уроках.
4. Список скиллов в ресурсе — это массив идентификаторов скиллов. Можно их указать и в другом виде, например в виде массива объектов, или ссылок. В любом случае, чтобы, например, все вывести на фронте (информацию про нашего техписа и про его скиллы, «под капотом» будет «дергаться» не один метод).
5. Контактные данные можно представить в виде массива с разными полями (телефон, сайт, канал в Телеграм и пр.). Но не будет усложнять. Пусть у нас будет 2 отдельных поля, одно из которых должно будет заполнено обязательно при добавлении в базу нового техписа.
По аналогии спроектируем ресурс «Навык»:
|Название поля|Имя поля в API|Тип данных|
|-------------|--------------|----------|
|Идентификатор|id|integer|
|Название навыка|skillName|string|
|Описание навыка|skillDescription|string|
|Алиас|alias|string|
|Подтверждающий документ|confirmingDocument|string|
|Ссылки на примеры|linksExamples|array(string)|
Что здесь нужно пояснить:
1. Поле «Подтверждающий документ» с типом string. В нашем случае это будет ссылка на изображение диплома, сертификата и пр.
2. Поле «Ссылки на примеры» с типом array(string). В нашем случае это будет массив со ссылками на примеры работ по данному навыку.
Что дальше? А дальше, имея представление о ресурсах и перечень действий, которые можно будет с ними выполнить, можно приступать к подготовке OpenAPI спецификации для нашего API.
Этим займемся в следующий раз.
А перед этим рекомендую ознакомиться с OpenAPI Specification v3.1.0 (хотя бы вскользь).
🔥6❤2👍1