5 + 1 मामला जहां REST API विनिर्देश एक बहुत बड़ी भूमिका निभाता है

यह लेख REST API परियोजना के लिए एक उपयोगी और प्रासंगिक विनिर्देश लिखने और समर्थन करने पर ध्यान केंद्रित करेगा, जो बहुत सारे अतिरिक्त कोड को बचाएगा, साथ ही साथ समग्र रूप से परियोजना की अखंडता, विश्वसनीयता और पारदर्शिता में सुधार करेगा।

RESTful API क्या है?

यह एक मिथक है।

गंभीरता से, यदि आपको लगता है कि आपके प्रोजेक्ट में एक RESTful API है, तो आप लगभग निश्चित रूप से गलत हैं। रेस्टफुल का विचार एक एपीआई का निर्माण करना है जो सभी मामलों में वास्तुशिल्प नियमों और आरईएसटी शैली द्वारा वर्णित प्रतिबंधों का अनुपालन करता है, लेकिन वास्तविक परिस्थितियों में यह लगभग असंभव है ।

एक ओर, आरईएसटी में बहुत अधिक अस्पष्ट और अस्पष्ट परिभाषाएं हैं। उदाहरण के लिए, HTTP विधियों और स्थिति कोड के शब्दकोशों में से कुछ शब्दों का उपयोग अभ्यास में उनके इच्छित उद्देश्य के लिए नहीं किया जाता है, जबकि उनमें से कई का उपयोग बिल्कुल नहीं किया जाता है।

दूसरी ओर, REST बहुत अधिक प्रतिबंध बनाता है। उदाहरण के लिए, वास्तविक दुनिया में संसाधनों का परमाणु उपयोग मोबाइल अनुप्रयोगों द्वारा उपयोग किए जाने वाले एपीआई के लिए तर्कसंगत नहीं है। अनुरोधों के बीच स्थिति को स्टोर करने के लिए एक पूर्ण इनकार अनिवार्य रूप से कई एपीआई में उपयोग किए जाने वाले उपयोगकर्ता सत्रों के तंत्र पर प्रतिबंध है।

लेकिन रुको, सब कुछ इतना बुरा नहीं है!

हमें REST API विनिर्देशन की आवश्यकता क्यों है?

इन कमियों के बावजूद, एक उचित दृष्टिकोण के साथ, REST अभी भी वास्तव में शांत एपीआई डिजाइन करने के लिए एक उत्कृष्ट आधार बना हुआ है। इस तरह के एपीआई में आंतरिक एकरूपता, एक स्पष्ट संरचना, सुविधाजनक प्रलेखन और अच्छी इकाई परीक्षण कवरेज होनी चाहिए। यह सब आपके एपीआई के लिए एक गुणवत्ता विनिर्देश विकसित करके प्राप्त किया जा सकता है।

सबसे अधिक बार, REST एपीआई विनिर्देश इसके प्रलेखन से जुड़ा हुआ है। पहले के विपरीत (जो आपके एपीआई का औपचारिक विवरण है), प्रलेखन का उद्देश्य लोगों द्वारा पढ़ा जाना है: उदाहरण के लिए, आपके एपीआई का उपयोग करके मोबाइल या वेब एप्लिकेशन के डेवलपर्स द्वारा।

हालांकि, वास्तव में प्रलेखन बनाने के अलावा, एक उचित एपीआई विवरण अभी भी बहुत सारे लाभ ला सकता है। इस लेख में, मैं विनिर्देश के सक्षम उपयोग का उपयोग करके कैसे, के उदाहरण साझा करना चाहता हूं:

• इकाई परीक्षण को सरल और अधिक विश्वसनीय बनाना;
• इनपुट डेटा के प्रीप्रोसेसिंग और सत्यापन को कॉन्फ़िगर करें;
• क्रमबद्धता को स्वचालित करें और प्रतिक्रियाओं की अखंडता सुनिश्चित करें;
• और यहां तक ​​कि स्थैतिक टाइपिंग का लाभ उठाएं।

OpenAPI

REST API का वर्णन करने के लिए आमतौर पर स्वीकृत प्रारूप OpenAPI है , जिसे स्वैगर के रूप में भी जाना जाता है। यह विनिर्देश JSON या YAML प्रारूप में एक एकल फ़ाइल है, जिसमें तीन खंड हैं:

• एक हेडर जिसमें एपीआई का नाम, विवरण और संस्करण है, साथ ही अतिरिक्त जानकारी भी है;
• परिभाषाओं के लिंक के साथ सभी संसाधनों का विवरण, जिसमें उनके पहचानकर्ता, HTTP तरीके, सभी इनपुट पैरामीटर और साथ ही प्रतिक्रिया निकाय के कोड और प्रारूप शामिल हैं;
• JSON स्कीमा प्रारूप में वस्तुओं की सभी परिभाषाएँ जिनका उपयोग इनपुट मापदंडों और प्रतिक्रियाओं में दोनों में किया जा सकता है।

OpenAPI में एक गंभीर खामी है - संरचना की जटिलता और, अक्सर, अतिरेक । एक छोटी परियोजना के लिए, विनिर्देशन JSON फ़ाइल की सामग्री जल्दी से कई हजार लाइनों तक बढ़ सकती है। इस रूप में इस फ़ाइल को मैन्युअल रूप से बनाए रखना संभव नहीं है। यह मौजूदा विनिर्देशों को बनाए रखने के विचार के लिए एक गंभीर खतरा है क्योंकि एपीआई विकसित होता है।

कई दृश्य संपादक हैं जो आपको एपीआई का वर्णन करने और परिणामस्वरूप ओपनएपीआई विनिर्देश बनाने की अनुमति देते हैं। बदले में, अतिरिक्त सेवाएं और क्लाउड समाधान उन पर आधारित हैं, उदाहरण के लिए, स्वैगर , एपरीर , स्टॉपलाइट , रेस्टलेट, और अन्य।

हालांकि, मेरे लिए, इस तरह की सेवाएं विनिर्देश को जल्दी से संपादित करने और कोड लेखन प्रक्रिया के साथ संयोजन करने की कठिनाई के कारण बहुत सुविधाजनक नहीं थीं। एक और माइनस प्रत्येक विशेष सेवा के कार्यों के सेट पर निर्भरता है। उदाहरण के लिए, पूर्ण सेवा इकाई परीक्षण को केवल क्लाउड सेवा के माध्यम से लागू करना लगभग असंभव है। कोड पीढ़ी और यहां तक ​​कि एंडपॉइंट के लिए "प्लग" का निर्माण, हालांकि यह बहुत संभव लगता है, व्यवहार में व्यावहारिक रूप से बेकार हैं।

Tinyspec

इस लेख में, मैं मूल REST API विवरण प्रारूप - tinyspec के आधार पर उदाहरणों का उपयोग करूंगा । प्रारूप छोटी फाइलें हैं जो एक सहज ज्ञान युक्त वाक्यविन्यास के साथ परियोजना में उपयोग किए जाने वाले समापन बिंदु और डेटा मॉडल का वर्णन करते हैं। फ़ाइलें कोड के बगल में संग्रहीत की जाती हैं, जो आपको उनके साथ जांच करने और उन्हें लिखने की प्रक्रिया में उन्हें सही तरीके से संपादित करने की अनुमति देता है। इसी समय, टिनिस्पेक स्वचालित रूप से एक पूर्ण ओपनएपीआई में संकलित किया जाता है, जिसे तुरंत परियोजना में उपयोग किया जा सकता है। यह वास्तव में आपको बताने का समय है।

इस लेख में, मैं Node.js (koa, express) और रूबी ऑन रेल्स से उदाहरण दूंगा, हालांकि ये प्रथाएं अधिकांश प्रौद्योगिकियों पर लागू होती हैं, जिनमें पायथन, पीएचपी और जावा शामिल हैं।

जब कल्पना अविश्वसनीय रूप से उपयोगी है

1. समापन बिंदुओं की इकाई-परीक्षण

व्यवहार चालित विकास (BDD) REST API विकसित करने के लिए आदर्श है। यूनिट परीक्षण लिखने का सबसे सुविधाजनक तरीका व्यक्तिगत कक्षाओं, मॉडल और नियंत्रकों के लिए नहीं है, बल्कि विशिष्ट समापन बिंदुओं के लिए है। प्रत्येक परीक्षण में, आप एक वास्तविक HTTP अनुरोध का अनुकरण करते हैं और सर्वर प्रतिक्रिया की जांच करते हैं। Node.js में, परीक्षण अनुरोधों के अनुकरण के लिए, रूबी ऑन रेल्स - एयरबोर्न में सुपरटेस्ट और ची- http हैं ।

मान लें कि हमारे पास एक User स्कीमा और एक GET /users समापन बिंदु है जो सभी उपयोगकर्ताओं को वापस करता है। यहाँ टिनिसेप सिंटैक्स है जो इसका वर्णन करता है:

1. User.models.tinyspec फ़ाइल:

 User {name, isAdmin: b, age?: i} 

1. फ़ाइल users.endpoint.tinyspec :

 GET /users => {users: User[]} 

इस प्रकार हमारा परीक्षण दिखेगा:

Node.js

 describe('/users', () => { it('List all users', async () => { const { status, body: { users } } = request.get('/users'); expect(status).to.equal(200); expect(users[0].name).to.be('string'); expect(users[0].isAdmin).to.be('boolean'); expect(users[0].age).to.be.oneOf(['boolean', null]); }); }); 

रूबी ऑन रेल्स

 describe 'GET /users' do it 'List all users' do get '/users' expect_status(200) expect_json_types('users.*', { name: :string, isAdmin: :boolean, age: :integer_or_null, }) end end 

जब हमारे पास एक विनिर्देश है जो सर्वर प्रतिक्रिया स्वरूपों का वर्णन करता है, तो हम परीक्षण को सरल कर सकते हैं और बस इस विनिर्देश के खिलाफ प्रतिक्रिया की जांच कर सकते हैं। ऐसा करने के लिए, हम इस तथ्य का लाभ उठाएंगे कि हमारे टिनिसेप मॉडल को ओपनएपीआई परिभाषाओं में बदल दिया गया है, जो कि JSON स्कीमा प्रारूप के अनुरूप हैं।

जेएस में कोई शाब्दिक वस्तु (या रूबी में Hash , पायथन में एक dict , पीएचपी में एक साहचर्य सरणी और यहां तक ​​कि जावा में एक Map ) को JSON योजना के अनुपालन के लिए परीक्षण किया जा सकता है। और टेस्टिंग फ्रेमवर्क के लिए भी समान प्लगइन्स हैं, उदाहरण के लिए RSPec के लिए jest-ajv ( npm ), chai-ajv-json-schema ( npm ) और json_matchers (rubygem)।

योजनाओं का उपयोग करने से पहले, आपको उन्हें परियोजना से जोड़ना होगा। सबसे पहले, हम टिनिस्पेक के आधार पर Openapi.json विनिर्देशन फ़ाइल जनरेट करेंगे (यह कार्रवाई स्वचालित रूप से प्रत्येक रन रन से पहले की जा सकती है:

 tinyspec -j -o openapi.json 

Node.js

अब हम परियोजना में प्राप्त JSON का उपयोग कर सकते हैं और इससे definitions ले सकते हैं, जिसमें JSON की सभी योजनाएँ शामिल हैं। योजनाओं में क्रॉस-रेफरेंस ( $ref ) शामिल हो सकते हैं, इसलिए, अगर हमारे पास नेस्टेड स्कीम हैं (उदाहरण के लिए, Blog {posts: Post[]} ), तो हमें उन्हें सत्यापन में उपयोग करने के लिए "विस्तार" करने की आवश्यकता है। ऐसा करने के लिए, हम json-schema-deref-sync ( npm ) का उपयोग करेंगे।

 import deref from 'json-schema-deref-sync'; const spec = require('./openapi.json'); const schemas = deref(spec).definitions; describe('/users', () => { it('List all users', async () => { const { status, body: { users } } = request.get('/users'); expect(status).to.equal(200); // Chai expect(users[0]).to.be.validWithSchema(schemas.User); // Jest expect(users[0]).toMatchSchema(schemas.User); }); }); 

रूबी ऑन रेल्स

json_matchers $ref लिंक को संभाल सकते हैं, लेकिन एक निश्चित तरीके से फ़ाइल सिस्टम में योजनाओं के साथ अलग-अलग फ़ाइलों की आवश्यकता होती है, इसलिए सबसे पहले आपको swagger.json को कई छोटी फ़ाइलों में विभाजित करना होगा ( यहाँ इस पर और अधिक):

 # ./spec/support/json_schemas.rb require 'json' require 'json_matchers/rspec' JsonMatchers.schema_root = 'spec/schemas' # Fix for json_matchers single-file restriction file = File.read 'spec/schemas/openapi.json' swagger = JSON.parse(file, symbolize_names: true) swagger[:definitions].keys.each do |key| File.open("spec/schemas/#{key}.json", 'w') do |f| f.write(JSON.pretty_generate({ '$ref': "swagger.json#/definitions/#{key}" })) end end 

उसके बाद, हम अपना टेस्ट इस तरह लिख सकते हैं:

 describe 'GET /users' do it 'List all users' do get '/users' expect_status(200) expect(result[:users][0]).to match_json_schema('User') end end 

नोट: इस तरह से परीक्षण लिखना अविश्वसनीय रूप से सुविधाजनक है। खासकर अगर आपका आईडीई रनिंग टेस्ट और डिबगिंग (जैसे वेबस्टॉर्म, रूबीमाइन और विजुअल स्टूडियो) का समर्थन करता है। इस प्रकार, आप किसी अन्य सॉफ़्टवेयर का उपयोग नहीं कर सकते हैं, और एपीआई का संपूर्ण विकास चक्र लगातार 3 चरणों तक कम हो जाता है:

1. विनिर्देश डिजाइन (जैसे टिनिस्पेक में);
2. जोड़ा / परिवर्तित समापन बिंदुओं के लिए परीक्षणों का एक पूरा सेट लिखना;
3. विकासशील कोड जो सभी परीक्षणों को संतुष्ट करता है।

2. इनपुट का सत्यापन

OpenAPI न केवल प्रतिक्रियाओं के प्रारूप का वर्णन करता है, बल्कि इनपुट डेटा भी है। यह हमें अनुरोध के दौरान उपयोगकर्ता से प्राप्त डेटा को सही तरीके से सत्यापित करने की अनुमति देता है।

मान लें कि हमारे पास निम्नलिखित विनिर्देश हैं जो उपयोगकर्ता डेटा को अद्यतन करने के साथ-साथ सभी क्षेत्रों को भी बदल सकते हैं:

 # user.models.tinyspec UserUpdate !{name?, age?: i} # users.endpoints.tinyspec PATCH /users/:id {user: UserUpdate} => {success: b} 

पहले हमने परीक्षणों के अंदर सत्यापन के लिए प्लगइन्स को देखा, हालांकि अधिक सामान्य मामलों के लिए ajv ( npm ) और json-schema (rubygem) सत्यापन मॉड्यूल हैं, चलो उनका उपयोग करते हैं और सत्यापन के साथ एक नियंत्रक लिखते हैं।

Node.js (Koa)

यह एक्सप्रेस के उत्तराधिकारी कोए के लिए एक उदाहरण है, लेकिन एक्सप्रेस के लिए, कोड समान दिखाई देगा।

 import Router from 'koa-router'; import Ajv from 'ajv'; import { schemas } from './schemas'; const router = new Router(); // Standard resource update action in Koa. router.patch('/:id', async (ctx) => { const updateData = ctx.body.user; // Validation using JSON schema from API specification. await validate(schemas.UserUpdate, updateData); const user = await User.findById(ctx.params.id); await user.update(updateData); ctx.body = { success: true }; }); async function validate(schema, data) { const ajv = new Ajv(); if (!ajv.validate(schema, data)) { const err = new Error(); err.errors = ajv.errors; throw err; } } 

इस उदाहरण में, यदि इनपुट विनिर्देश को पूरा नहीं करता है, तो सर्वर क्लाइंट को 500 Internal Server Error प्रतिक्रिया देगा। ऐसा होने से रोकने के लिए, हम सत्यापनकर्ता त्रुटि को रोक सकते हैं और अपनी प्रतिक्रिया बना सकते हैं, जिसमें विशिष्ट क्षेत्रों के बारे में अधिक विस्तृत जानकारी होगी जो परीक्षण में उत्तीर्ण नहीं हुए हैं, और विनिर्देश का अनुपालन भी करते हैं ।

FieldsValidationError मॉडल का FieldsValidationError फ़ाइल में विवरण जोड़ें:

 Error {error: b, message} InvalidField {name, message} FieldsValidationError < Error {fields: InvalidField[]} 

और अब हम इसे हमारे समापन बिंदु के संभावित उत्तरों में से एक के रूप में दर्शाते हैं:

 PATCH /users/:id {user: UserUpdate} => 200 {success: b} => 422 FieldsValidationError 

यह दृष्टिकोण आपको इकाई परीक्षण लिखने की अनुमति देता है जो क्लाइंट से प्राप्त गलत डेटा के साथ त्रुटियों के गठन की शुद्धता को सत्यापित करता है।

3. मॉडल का सीरियलाइजेशन

लगभग सभी आधुनिक सर्वर फ्रेमवर्क एक या दूसरे तरीके से ORM का उपयोग करते हैं। इसका मतलब है कि सिस्टम के अंदर एपीआई में उपयोग किए जाने वाले अधिकांश संसाधन मॉडल, उनके उदाहरण और संग्रह के रूप में प्रस्तुत किए जाते हैं।

एपीआई प्रतिक्रिया में संचरण के लिए इन संस्थाओं के JSON प्रतिनिधित्व को उत्पन्न करने की प्रक्रिया को क्रमांकन कहा जाता है। विभिन्न चौखटे के लिए कई प्लगइन्स हैं जो क्रमबद्धता के कार्य करते हैं, उदाहरण के लिए: सीक्वलाइज़-टू-जोंसन (एनपीएम), कृत्यों_स_पाइ (रूबीगैम), जोंसापी-रेल्स (रूबीगैम)। वास्तव में, ये प्लगइन्स एक विशिष्ट मॉडल के लिए उन क्षेत्रों की एक सूची निर्दिष्ट करने की अनुमति देते हैं जिन्हें JSON ऑब्जेक्ट में शामिल किया जाना चाहिए, साथ ही अतिरिक्त नियम, उदाहरण के लिए, उनका नाम बदलने या गतिशील रूप से मानों की गणना करने के लिए।

कठिनाइयाँ तब शुरू होती हैं जब हमें एक ही मॉडल के कई अलग-अलग JSON निरूपण करने की आवश्यकता होती है या जब किसी ऑब्जेक्ट में नेस्टेड संस्थाएँ - संघ होते हैं। धारावाहिकों की विरासत, पुन: उपयोग और जोड़ने की आवश्यकता है ।

विभिन्न मॉड्यूल इन समस्याओं को अलग-अलग तरीकों से हल करते हैं, लेकिन चलो सोचते हैं कि क्या विनिर्देश हमें फिर से मदद कर सकते हैं? वास्तव में, वास्तव में, JSON प्रतिनिधित्व के लिए आवश्यकताओं के बारे में सभी जानकारी, नेस्टेड संस्थाओं सहित क्षेत्रों के सभी संभावित संयोजन पहले से ही इसमें हैं। तो हम एक स्वचालित क्रमबद्धक लिख सकते हैं।

मैं आपके ध्यान में एक छोटा मॉड्यूल सीक्वल-सीरीज़-सीरीज़ (एनपीएम) लाता हूं , जो आपको सीक्वेलाइज़ मॉडल के लिए ऐसा करने की अनुमति देता है। यह मॉडल या एक सरणी, साथ ही आवश्यक सर्किट का एक उदाहरण लेता है, और पुनरावृत्त क्रमबद्ध ऑब्जेक्ट का निर्माण करता है, सभी आवश्यक फ़ील्ड को ध्यान में रखता है और संबंधित संस्थाओं के लिए नेस्टेड सर्किट का उपयोग करता है।

तो, मान लें कि हमें एपीआई से उन सभी उपयोगकर्ताओं को वापस लौटना होगा जिनके पास ब्लॉग पोस्ट हैं, उन पोस्ट पर टिप्पणियों सहित। हम निम्नलिखित विनिर्देशन का उपयोग करते हुए इसका वर्णन करते हैं:

 # models.tinyspec Comment {authorId: i, message} Post {topic, message, comments?: Comment[]} User {name, isAdmin: b, age?: i} UserWithPosts < User {posts: Post[]} # blogUsers.endpoints.tinyspec GET /blog/users => {users: UserWithPosts[]} 

अब हम Sequelize का उपयोग करके क्वेरी का निर्माण कर सकते हैं और एक सीरियलाइज्ड ऑब्जेक्ट को वापस कर सकते हैं जो कि ऊपर वर्णित विनिर्देश से बिल्कुल मेल खाता है:

 import Router from 'koa-router'; import serialize from 'sequelize-serialize'; import { schemas } from './schemas'; const router = new Router(); router.get('/blog/users', async (ctx) => { const users = await User.findAll({ include: [{ association: User.posts, required: true, include: [Post.comments] }] }); ctx.body = serialize(users, schemas.UserWithPosts); }); 

यह लगभग जादू है, है ना?

4. स्टेटिक टाइपिंग

यदि आप इतने शांत हैं कि आप टाइपस्क्रिप्ट या फ्लो का उपयोग कर रहे हैं, तो आप पहले ही सोच सकते हैं, "मेरे प्रिय स्थिर प्रकारों के बारे में क्या!" । Sw2dts या swagger -to-flowtype मॉड्यूल का उपयोग करते हुए , आप JSON योजनाओं के आधार पर सभी आवश्यक परिभाषाएँ तैयार कर सकते हैं और उनका उपयोग परीक्षण, इनपुट डेटा और क्रमबद्धकों के स्थैतिक टाइपिंग के लिए कर सकते हैं।

 tinyspec -j sw2dts ./swagger.json -o Api.d.ts --namespace Api 

अब हम नियंत्रकों में प्रकारों का उपयोग कर सकते हैं:

 router.patch('/users/:id', async (ctx) => { // Specify type for request data object const userData: Api.UserUpdate = ctx.request.body.user; // Run spec validation await validate(schemas.UserUpdate, userData); // Query the database const user = await User.findById(ctx.params.id); await user.update(userData); // Return serialized result const serialized: Api.User = serialize(user, schemas.User); ctx.body = { user: serialized }; }); 

और परीक्षणों में:

 it('Update user', async () => { // Static check for test input data. const updateData: Api.UserUpdate = { name: MODIFIED }; const res = await request.patch('/users/1', { user: updateData }); // Type helper for request response: const user: Api.User = res.body.user; expect(user).to.be.validWithSchema(schemas.User); expect(user).to.containSubset(updateData); }); 

कृपया ध्यान दें कि उत्पन्न प्रकार की परिभाषाओं का उपयोग केवल एपीआई परियोजना में ही नहीं किया जा सकता है, बल्कि क्लाइंट एप्लिकेशन परियोजनाओं में भी किया जा सकता है, जिसमें उन प्रकार के कार्यों का वर्णन किया जाता है जिनमें एपीआई काम करता है। कोणीय ग्राहक डेवलपर्स इस उपहार से विशेष रूप से प्रसन्न होंगे।

5. क्वेरी स्ट्रिंग का रूपांतरण

यदि किसी कारण से आपका API MIME प्रकार के application/x-www-form-urlencoded साथ अनुरोध स्वीकार करता है और application/json , तो अनुरोध निकाय इस तरह दिखाई देगा:

 param1=value&param2=777&param3=false 

वही क्वेरी मापदंडों पर लागू होता है (उदाहरण के लिए, GET अनुरोधों में)। इस मामले में, वेब सर्वर स्वचालित रूप से प्रकारों को पहचानने में सक्षम नहीं होगा - सारा डेटा स्ट्रिंग्स के रूप में होगा ( यहां qpm npm मॉड्यूल रिपॉजिटरी में एक चर्चा है), इसलिए पार्स करने के बाद आपको निम्न ऑब्जेक्ट मिलेगा:

 { param1: 'value', param2: '777', param3: 'false' } 

इस मामले में, योजना के अनुसार अनुरोध को मान्य नहीं किया जाएगा, जिसका अर्थ है कि मैन्युअल रूप से सत्यापित करना आवश्यक होगा कि प्रत्येक पैरामीटर का सही प्रारूप है और इसे आवश्यक प्रकार पर लाएं।

जैसा कि आप अनुमान लगा सकते हैं, यह हमारे विनिर्देश से सभी समान योजनाओं का उपयोग करके किया जा सकता है। कल्पना कीजिए कि हमारे पास ऐसा समापन बिंदु और योजना है:

 # posts.endpoints.tinyspec GET /posts?PostsQuery # post.models.tinyspec PostsQuery { search, limit: i, offset: i, filter: { isRead: b } } 

इस तरह के समापन बिंदु के लिए अनुरोध का एक उदाहरण यहां दिया गया है

 GET /posts?search=needle&offset=10&limit=1&filter[isRead]=true 

आइए एक castQuery फ़ंक्शन लिखें, जो सभी मापदंडों को हमारे लिए आवश्यक प्रकारों में बदल देगा। यह कुछ इस तरह दिखेगा:

 function castQuery(query, schema) { _.mapValues(query, (value, key) => { const { type } = schema.properties[key] || {}; if (!value || !type) { return value; } switch (type) { case 'integer': return parseInt(value, 10); case 'number': return parseFloat(value); case 'boolean': return value !== 'false'; default: return value; } }); } 

नेस्टेड स्कीमों, सरणियों और null प्रकारों के समर्थन के साथ इसका अधिक पूर्ण कार्यान्वयन कास्ट-के-स्कीमा (एनपीएम) में उपलब्ध है। अब हम इसे अपने कोड में उपयोग कर सकते हैं:

 router.get('/posts', async (ctx) => { // Cast parameters to expected types const query = castQuery(ctx.query, schemas.PostsQuery); // Run spec validation await validate(schemas.PostsQuery, query); // Query the database const posts = await Post.search(query); // Return serialized result ctx.body = { posts: serialize(posts, schemas.Post) }; }); 

ध्यान दें कि समापन बिंदु कोड की चार पंक्तियाँ, विनिर्देशन से तीन उपयोग योजनाएँ।

सर्वोत्तम अभ्यास

बनाने और संशोधित करने के लिए अलग-अलग योजनाएँ

आमतौर पर, सर्वर प्रतिक्रिया का वर्णन करने वाली योजनाएं उन लोगों से भिन्न होती हैं जो मॉडल बनाने और संशोधित करने के लिए उपयोग किए गए इनपुट का वर्णन करते हैं। उदाहरण के लिए, POST और PATCH अनुरोधों के लिए उपलब्ध क्षेत्रों की सूची को कड़ाई से सीमित किया जाना चाहिए, जबकि PATCH अनुरोधों में, आमतौर पर योजना के सभी क्षेत्रों को वैकल्पिक बनाया जाता है। उत्तर निर्धारित करने वाली योजनाएँ अधिक निःशुल्क हो सकती हैं।

Tinyspec CRUDL एंडपॉइंट की स्वचालित पीढ़ी New और Update पोस्टफिक्स का उपयोग करती है। User* को इस प्रकार परिभाषित किया जा सकता है:

 User {id, email, name, isAdmin: b} UserNew !{email, name} UserUpdate !{email?, name?} 

पुरानी योजनाओं के पुन: उपयोग या विरासत के कारण आकस्मिक सुरक्षा समस्याओं से बचने के लिए विभिन्न प्रकार के कार्यों के लिए समान योजनाओं का उपयोग न करने का प्रयास करें।

स्कीमा नामों में शब्दार्थ

एक ही मॉडल की सामग्री अलग-अलग समापन बिंदुओं में भिन्न हो सकती है। स्कीमा नामों में पोस्ट के With* और For* प्रयोग करें, यह दिखाने के लिए कि वे कैसे भिन्न हैं और वे किस लिए हैं। टिनिसेप में मॉडल एक दूसरे से विरासत में भी मिल सकते हैं। उदाहरण के लिए:

 User {name, surname} UserWithPhotos < User {photos: Photo[]} UserForAdmin < User {id, email, lastLoginAt: d} 

उपसर्ग विविध और संयुक्त हो सकते हैं। मुख्य बात यह है कि उनका नाम सार को दर्शाता है और प्रलेखन के साथ परिचितता को सरल करता है।

क्लाइंट प्रकार द्वारा एंडपॉइंट का पृथक्करण

अक्सर एक ही एंडपॉइंट ग्राहक के प्रकार या एंडपॉइंट तक पहुंचने वाले उपयोगकर्ता की भूमिका के आधार पर अलग-अलग डेटा लौटाते हैं। उदाहरण के लिए, GET /users और GET /messages के समापन बिंदु आपके मोबाइल एप्लिकेशन के उपयोगकर्ताओं और बैक ऑफिस प्रबंधकों के लिए बहुत भिन्न हो सकते हैं। एक ही समय में, समापन बिंदु का नाम बदलने से बहुत अधिक जटिलता हो सकती है।

कई बार एक ही समापन बिंदु का वर्णन करने के लिए, आप पथ के बाद इसके प्रकार कोष्ठक में जोड़ सकते हैं। इसके अलावा, टैग का उपयोग करना उपयोगी है: यह आपके समापन बिंदुओं के प्रलेखन को समूहों में विभाजित करने में मदद करेगा, जिनमें से प्रत्येक को आपके एपीआई के ग्राहकों के एक विशिष्ट समूह के लिए डिज़ाइन किया जाएगा। उदाहरण के लिए:

 Mobile app: GET /users (mobile) => UserForMobile[] CRM admin panel: GET /users (admin) => UserForAdmin[] 

अन्य एपीआई प्रलेखन

एक बार जब आपके पास टिनिसेप या ओपनएपीआई प्रारूप में एक विनिर्देश होता है, तो आप एचटीएमएल में सुंदर दस्तावेज तैयार कर सकते हैं और इसे अपने एपीआई का उपयोग करके डेवलपर्स की खुशी के लिए प्रकाशित कर सकते हैं।

पहले बताई गई क्लाउड सेवाओं के अलावा, CLI उपकरण हैं जो OpenAPI 2.0 को HTML और PDF में परिवर्तित करते हैं, जिसके बाद आप इसे किसी भी स्थैतिक होस्टिंग में डाउनलोड कर सकते हैं। उदाहरण:

• बूटप्रिंट-ओपेनपी (एनपीएम, टिनिस्पेक में डिफ़ॉल्ट रूप से उपयोग किया जाता है)
• swagger2markup-cli (जार, उपयोग का एक उदाहरण है , इसका उपयोग टिनिसेप क्लाउड में किया जाएगा)
• redoc-cli ( npm )
• widdershins (npm)

क्या आप और उदाहरण जानते हैं? उन्हें टिप्पणियों में साझा करें।

दुर्भाग्य से, OpenAPI 3.0, एक साल पहले जारी किया गया था, अभी भी खराब रूप से समर्थित है, और मुझे इसके आधार पर प्रलेखन के किसी भी योग्य उदाहरण नहीं मिले: न तो क्लाउड समाधानों के बीच, न ही सीएलआई उपकरणों के बीच। इसी कारण से, OpenAPI 3.0 अभी तक टिनिसेप में समर्थित नहीं है।

GitHub पर प्रकाशित करें

प्रलेखन प्रकाशित करने का सबसे आसान तरीका GitHub Pages है । बस अपनी रिपॉजिटरी सेटिंग्स में /docs डायरेक्टरी के लिए स्टैटिक पेज सपोर्ट को सक्षम करें और इस फोल्डर में HTML डॉक्यूमेंट को स्टोर करें।

आप संकुल में scripts में tinyspec या किसी अन्य CLI टूल के माध्यम से प्रलेखन उत्पन्न करने के लिए एक कमांड जोड़ सकते हैं।

 "scripts": { "docs": "tinyspec -h -o docs/", "precommit": "npm run docs" } 

निरंतर एकीकरण

आप डॉक्यूमेंट जनरेशन को CI चक्र में शामिल कर सकते हैं और इसे प्रकाशित कर सकते हैं, उदाहरण के लिए, अमेजन S3 में आपके API के वातावरण या संस्करण के आधार पर विभिन्न पतों के तहत, उदाहरण के लिए: /docs/2.0 , /docs/stable , /docs/staging ।

टिनिसेप मेघ

यदि आपको टिनिसेप सिंटैक्स पसंद आया है, तो आप टिनिसेपेक.क्लाउड में एक शुरुआती गोद लेने वाले के रूप में पंजीकरण कर सकते हैं। हम इसके आधार पर एक क्लाउड सेवा और CLI के निर्माण के लिए जा रहे हैं, जो दस्तावेजों के एक विस्तृत चयन और अपने स्वयं के टेम्पलेट्स को विकसित करने की क्षमता के साथ प्रलेखन के स्वचालित प्रकाशन के लिए CLI है।

निष्कर्ष

REST API का विकास शायद सभी की सबसे सुखद गतिविधि है जो आधुनिक वेब और मोबाइल सेवाओं पर काम करने की प्रक्रिया में मौजूद है। ब्राउज़र, ऑपरेटिंग सिस्टम और स्क्रीन आकार का कोई चिड़ियाघर नहीं है, सब कुछ पूरी तरह से हमारे नियंत्रण में है - "आपकी उंगलियों पर"।

विभिन्न स्वचालन के रूप में वर्तमान विनिर्देश और बोनस बनाए रखना, जो एक ही समय में प्रदान किए जाते हैं, इस प्रक्रिया को और भी सुखद बनाते हैं। ऐसा एपीआई संरचित, पारदर्शी और विश्वसनीय हो जाता है।

दरअसल, वास्तव में, भले ही हम एक मिथक के निर्माण में लगे हों, फिर भी हम इसे सुंदर क्यों नहीं बनाते?