FishText API — РыбаТекст — онлайн-генератор случайного текста, Lorem Ipsum на русском

Зачем API фиштексту?

Например, если ты разработчик, пилишь крутой сайт — и тебе нужно вывести пример списка статей. Или проверить вёрстку на стрессоустойчивость — и при автотестах заполнить её пятнадцатью абзацами текста. Или ты торгуешь шаблонами для сайтов — и тебе лень каждый раз заполнять их контентом. Вариантов масса.

Ну и вообще. У каждого крутого сервиса должен быть API. А мы крутые.

Как это работает?

Очень просто: достаточно отправить GET-запрос на наш сервер, указав, сколько и какого типа контента нужно получить (предложений, абзацев или заголовков). Кроме того, можно указать формат получения рыботекста (HTML или JSON).

Запрос

URL и HTTP-метод запроса к API. В качестве метода можно использовать только GET.

Параметр	Значение
URL	https://fish-text.ru/get
HTTP Method	GET

Параметры запроса

Список параметров, которые принимает API фиштекста.

Параметр	Тип	Значение
`type`	string	`sentence` вернет указанное количество предложений (по-умолчанию) `paragraph` вернет указанное количество абзацев `title` вернет указанное количество заголовков
`number`	int	`1-500` количество предложений, которые можно запросить единовременно (по-умолчанию: 3) `1-100` то же самое, но для абзацев (по-умолчанию: 3) `1-500` то же самое, но для заголовков (по-умолчанию: 1)
`format`	string	`json` вернет JSON-строку со статусом, текстом и кодом ошибки, если она есть (по-умолчанию) `html` вернет чистый HTML, разбитый помощью тега `<p>`или `<h1>`

Ответы

Формат ответа сервера зависит от параметра format в запросе и может быть JSON-сторокой или чистым HTML.

Ответ в формате JSON

Параметр	Тип	Значение
`status`	string	`success` в случае успешного выполнения `error` если что-то пошло не так
`text`	string	здесь будет сам рыбатекст в случае успешного выполнения запроса или текстовое описание ошибки в случае какого-то фэйла
`errorCode`	int	`1X-3X` код ошибки, если она есть

В JSON-ответе абзацы отделены друг от друга символами \n\n

Ответ в формате HTML

Представляет из себя простой HTML с рыбатекстом, разбитым на абзацы с помощью тега <p> (если вы запросили предложения или абзацы) или на заголовки с помощью тега <h1> (если вы запросили заголовки).
Даже если вы запрашиваете всего лишь несколько предложений, они будут также обернуты в тег параграфа — это сделано для унификации размещения текста-рыбы разной длины. Пример поля, в котором могут быть размещены как несколько предложений, так и целые абзацы тестового текста, можно наблюдать на главной странице.
Каждый заголовок, в свою очередь, будет обернут в отдельный html-элемент.

Ограничения

API фиштекста имеет два типа ограничений: на количество запрашиваемого тестового контента и на количество обращений в минуту.

Ограничения на количество контента

В рамках одного запроса можно получить только 100 абзацев, 500 предложений или 500 заголовков. При указании параметра number больше данных значений, сервер вернет сообщение об ошибке. Для подавляющего большинства случаев ста абзацев или пятиста предложений более чем достаточно.

Ограничения на количество обращений

В течение одной минуты можно совершать не более 600 обращений к API (10 в секунду). После превышения этого лимита доступ к API будет заблокирован на 120 секунд, а сервер станет возвращать соответствующую ошибку. Если по каким-то причинам вам нужно более 600 обращений в минуту, пишите на dev@fish-text.ru, обсудим.

Коды и заголовки ошибок

Тип сообщений об ошибках формируется на основании параметра type запроса. Для ответов в формате JSON выводится JSON-строка со статусом, кодом и текстом ошибки, а для ответов в формате HTML — только текст ошибки и соответствующий HTTP-заголовок.

Код (JSON)	HTTP-заголовок (HTML)	Значение
`11`	`200 OK`	Превышен допустимый объём запрашиваемого контента
`21`	`403 Forbidden`	IP заблокирован на 120 секунд из-за превышения лимита обращений
`22`	`403 Forbidden`	IP заблокирован навсегда
`31`	`500 Internal Server Error`	Неизвестная ошибка сервера

Примеры

Ниже приведены несколько примеров использования FishText API. Ответы сервера (response) по понятным причинам сокращены.

Пример 1: два абзаца рыбатекста в формате JSON

Для более подробного разъяснения, в примере запрос выполняется с помощью XMLHttpRequest, но вы можете использовать любой другой способ, в том числе прямой GET-запрос. Кроме того, в запросе мы не указываем параметр format, потому что он по умолчанию — json.

Запрос:

// проверяем на поддержку современного XMLHttpRequest
var XHR = ("onload" in new XMLHttpRequest()) ? XMLHttpRequest : XDomainRequest;
// создаём новый объект XMLHttpRequest
var xhr = new XHR();
// присваиваем переменным параметры запроса (для наглядности)
var type = 'paragraph'; // тип получаемого контента (абзацы)
var number = 2; // количество абзацев
// собираем параметры запроса,
// не указываем format, потому что он по умолчанию — "json"
var params = '&type=' + type + '&number=' + number;
// отправляем запрос
xhr.open('GET', 'https://fish-text.ru/get?' + params, true);
// обрабатываем успешный запрос
xhr.onload = function () {
  // парсим ответ сервера
  var result = JSON.parse(this.responseText);
  // проверяем статус ответа
  if (result.status === 'success') {
    // выводим рыбатекст
    console.log(result.text);
  } else {
    // выводим код и текст ошибки
    console.log(result.errorCode + '\n' + result.text);
  }
};
// обрабатываем неудачный запрос
xhr.onerror = function () {
  alert('Ошибка ' + this.status);
};
// отправляем запрос
xhr.send();

Успешный ответ (сам текст-рыба сокращен):

{
  "status": "success",
  "text": "\u0421\u043b\u0435 <...> \u043e\u043d\u043e\\n\\n <...> \u0437\u0430\u0447.\\n\\n"
}

Ответ с ошибкой (превышение лимита на количество контента):

{
  "status": "error",
  "text": "You requested too much content. Be more moderate.",
  "errorCode": 11
}

Пример 2: пять предложений рыбатекста в формате HTML

В примере указан простой GET-запрос, но вы можете вызывать метод иначе, любым удобным для вас способом. Можно не указывать type, потому что он по умолчанию равен sentence.

Запрос:

https://fish-text.ru/get?format=html&number=5

Успешный ответ:

<p>Но курс на социально-ориентированный национальный проект предопределяет высокую востребованность системы массового участия. Современные технологии достигли такого уровня, что начало ... дальнейших направлений развития.<p>

Ответ с ошибкой (временная блокировка):

Your IP is blocked due to too frequent calls. Try later.

В данном случае в HTTP-заголовках ответа сервера будет указано 403 Forbidden

Пример 3: один заголовок рыбатекста в формате HTML

Можно не указывать number, потому что он по умолчанию равен 1.

Запрос:

https://fish-text.ru/get?type=title&format=html

Успешный ответ:

<h1>Мелочь, а приятно: склады ломятся от зерна<h1>

Ответ с ошибкой (постоянная блокировка):

Your IP is permanently blocked. Contact the administration.

В данном случае в HTTP-заголовках ответа сервера будет указано 403 Forbidden

Обнаружили баг?

Если вы заметили ошибку в описании или работе API рыбатекста — напишите, пожалуйста, на dev@fish-text.ru, мы будем крайне признательны.