Боравенето с пагиниране в REST API е решаващ аспект от дизайна на API, особено за доставчик на API като нас. Пагинацията ни позволява да управляваме ефективно големи набори от данни, подобрявайки производителността и потребителското изживяване. В този блог ще проучим различни техники за работа с пагинация в REST API, ще обсъдим техните предимства и недостатъци и ще предоставим практически примери.
Защо е необходимо пагиниране
Когато работите с големи набори от данни, връщането на всички данни в един отговор може да бъде неефективно и изискващо много ресурси. Това може да доведе до дълго време за реакция, голямо използване на паметта както от страна на сървъра, така и от страна на клиента и потенциално претоварване на мрежата. Пагинирането решава тези проблеми, като разделя набора от данни на по-малки, по-управляеми „страници“ и връща страница по страница.
Често срещани техники за пагиниране
Отместване - ограничаване на страниците
Офсет - ограничаване на пагинацията е една от най-простите и често използвани техники. Това включва посочване на два параметъра:офсетилимит. Theофсетпоказва началната позиция на данните за извличане, алимитопределя максималния брой елементи, които да се върнат в отговора.
Например, ако имаме API крайна точка/api/продуктикойто връща списък с продукти, заявка сотместване = 20иограничение = 10ще върне 21-ия до 30-ия продукт.
Следното е пример на Python Flask за внедряване на отместване - ограничаване на странирането:
from flask import Flask, request, jsonify app = Flask(__name__) products = [{"id": i, "name": f"Product {i}"} for i in range(100)] @app.route('/api/products', methods=['GET']) def get_products(): offset = int(request.args.get('offset', 0)) limit = int(request.args.get('limit', 10)) paginated_products = products[offset:offset + limit] return jsonify(paginated_products) if __name__ == '__main__': app.run(debug=True)плюсове:
- Лесен за разбиране и изпълнение.
- Работи добре с бази данни, които поддържат
ОГРАНИЧЕНИЕиИЗМЕСТВАНЕклаузи, като MySQL и PostgreSQL.
минуси:
- Като
офсетстойността се увеличава, производителността може да се влоши значително, особено за големи масиви от данни. Това е така, защото базата данни трябва да прескочи голям брой редове, за да достигне желаното отместване. - Може да е трудно да се обработват данни, които се актуализират по време на страниране, тъй като отместването може вече да не сочи към правилната позиция.
Курсор - Пагинация на базата
Пагинацията, базирана на курсора, използва уникален идентификатор (курсора), за да маркира позицията в набора от данни. Вместо да посочи отместване, клиентът предоставя стойността на курсора в заявката, за да получи следващата страница с данни.
Например, ако имаме списък с потребители, сортирани по дата на тяхното създаване, курсорът може да бъде датата на създаване на последния потребител в предишната страница. Тогава сървърът ще върне следващия набор от потребители с дата на създаване, по-голяма от стойността на курсора.
Ето един прост пример на JavaScript с използване на Node.js и Express:
const express = require('express'); const app = express(); const users = [ { id: 1, name: 'User 1', created_at: '2023-01-01' }, { id: 2, name: 'User 2', created_at: '2023-01-02' }, // още потребители... ]; app.get('/api/users', (req, res) => { const cursor = req.query.cursor; const limit = parseInt(req.query.limit) || 10; let startIndex = 0; if (cursor) { startIndex = users.findIndex(user => user.created_at > cursor); } const paginatedUsers = users.slice(startIndex + limit); const nextCursor.length > 0 ?paginatedUsers.length - 1].created_at: null; app.listen(3000, () => { console.log('Сървър, работещ на порт 3000'); });плюсове:
- По-добра производителност в сравнение с офсет - ограничаване на странирането, особено за големи набори от данни. Не е необходимо базата данни да прескача голям брой редове.
- По-стабилен при работа с актуализации на данни, тъй като курсорът винаги сочи към конкретна позиция в набора от данни.
минуси:
- По-сложно за изпълнение, особено когато се работи с множество критерии за сортиране.
- Изисква уникален и сортируем идентификатор за използване като курсор.
Пагиниране на номер на страница
Пагинирането на номера на страници е подобно на отместване - ограничаване на пагинирането, но вместо да посочи отместване, клиентът изисква конкретен номер на страница. Сървърът изчислява отместването въз основа на номера на страницата и ограничението.
Например, ако ограничението е 10 елемента на страница, заявка за страница 3 ще има отместване от 20 (тъй катоотместване = (номер_на_страница - 1) * ограничение).
from flask import Flask, request, jsonify app = Flask(__name__) products = [{"id": i, "name": f"Product {i}"} for i in range(100)] @app.route('/api/products', methods=['GET']) def get_products(): page = int(request.args.get('page', 1)) limit = int(request.args.get('limit', 10)) offset = (page - 1) * limit paginated_products = products[offset:offset + limit] return jsonify(paginated_products) if __name__ == '__main__': app.run(debug=True)плюсове:
- Лесно за разбиране от потребителите, тъй като е подобно на традиционното страниране в уеб страниците.
- Лесен за изпълнение.
минуси:
- Подобно на офсет - ограничаване на пагинацията, може да страда от проблеми с производителността, когато броят на страниците се увеличава.
- Може да е трудно да се справите с актуализации на данни по време на пагиниране.
Съображения за доставчиците на API
Като доставчик на API трябва да вземем предвид няколко фактора, когато внедряваме страниране:
Стандартизация
Трябва да следваме индустриалните стандартни практики за пагинация. Това включва използването на последователни имена на параметри (като напрофсет,лимит,страница,курсор) и предоставяне на ясна документация за това как работи пагинирането.
Метаданни
В допълнение към пагинираните данни трябва да предоставим метаданни в отговора, като общия брой елементи, общия брой страници и връзки към следващата и предишната страница. Това помага на клиента да разбере по-добре набора от данни и да навигира през страниците.
Например отговорът може да бъде в следния формат:
{ "данни": [ { "id": 1, "name": "Продукт 1" }, { "id": 2, "name": "Продукт 2" } ], "total_items": 100, "total_pages": 10, "next_page": "/api/products?offset=20&limit=10", "prev_page": null }сигурност
Трябва да гарантираме, че параметрите за страниране са правилно валидирани, за да предотвратим SQL инжектиране или други уязвимости в сигурността. Например, трябва да конвертирамеофсетилимитпараметрите до цели числа и задайте разумни граници, за да предотвратите прекомерната консумация на ресурси.
Заключение
Боравенето с пагиниране в REST API е важно умение за доставчиците на API. Чрез избора на правилната техника за страниране въз основа на размера на набора от данни, изискванията за производителност и потребителското изживяване, можем да предоставим по-ефективен и удобен за потребителя API. Независимо дали имате работа с малък набор от данни или широкомащабно приложение, разбирането на плюсовете и минусите на различните методи за страниране е от съществено значение.
Ако се интересувате от нашите API или имате някакви въпроси относно пагинацията или други теми, свързани с API, не се колебайте да се свържете с нас за доставка и допълнителни дискусии. Ние също така предлагаме широка гама от продукти катоМетокарбамол,Азасетрон хидрохлорид, иПиразинамид.
Референции
- Ричардсън, Леонард и Сам Руби. RESTful уеб услуги. O'Reilly Media, 2007 г.
- Банкс, Адам. Изграждане на RESTful уеб API с Python и Flask. Издателство Пакет, 2018 г.