Symfony2 पर एक रीस्ट एपीआई को लागू करना: सही तरीका

REST API बनाना कोई आसान काम नहीं है। नहीं, गंभीरता से! यदि आप एपीआई को सही तरीके से लिखना चाहते हैं, तो आपको बहुत कुछ सोचना होगा, यह तय करना होगा कि व्यावहारिक होना चाहिए, या एपीआई पागल होना चाहिए। REST केवल GET, POST, PUT और Delete नहीं है। व्यवहार में, आपके पास संसाधनों के बीच बातचीत हो सकती है, आपको संसाधनों को कहीं और स्थानांतरित करने की आवश्यकता है (उदाहरण के लिए, एक पेड़ के अंदर), या आप एक विशिष्ट संसाधन मान प्राप्त करना चाहते हैं।

इस लेख में वह सब कुछ है जो मैंने इस उद्देश्य के लिए Symfony2 , FOSRestBundle , NelmioApiDocBundle और Propel का उपयोग करके विभिन्न API सेवाओं को लागू करके सीखा। उदाहरण के लिए, हम उपयोगकर्ताओं के साथ काम करने के लिए एक एपीआई बनाएंगे।

क्या आप बोलते हैं ...?

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

इसके अलावा, आपको यह भी पता होना चाहिए कि ग्राहकों के साथ संवाद कैसे करें, और HTTP प्रोटोकॉल, अर्थात् हेडर स्वीकार करें , इसमें हमारी मदद करेंगे। संक्षेप में, ग्राहक एक हेडर भेजेंगे जिसके साथ वे उस डेटा प्रारूप के प्रकार को प्राप्त करना चाहेंगे जिसे वे प्राप्त करना चाहते हैं।

हालाँकि, FOSRestBundle में आपके लिए सब कुछ पहले से ही किया गया है। इस भाग को ट्रैक करने की आवश्यकता है, लेकिन आपको उन सेटिंग्स में निर्धारित करना होगा जो आप समर्थन करना चाहते हैं। सबसे अधिक संभावना है, आप आमतौर पर JSON का उपयोग करते हैं, लेकिन यदि आप शब्दार्थ की समस्या में आते हैं, तो आप XML भेजेंगे। इस हिस्से को बाद में भी उजागर किया जाएगा।

क्या मिलता है?

HTTP GET विधि idempotent है। इसका मतलब है कि इस पद्धति का उपयोग करके आप कितनी बार डेटा का अनुरोध करते हैं, आपको एक ही डेटा प्राप्त करना होगा। उन्हें कोई बदलाव नहीं होना चाहिए। संसाधन प्राप्त करने के लिए GET का उपयोग करें: एक संग्रह या एक अलग संसाधन। Symfony2 में, रूटिंग नियम विवरण कुछ इस तरह दिखेगा:

# src/Acme/DemoBundle/Resources/config/routing.yml acme_demo_user_all: pattern: /users defaults: { _controller: AcmeDemoBundle:User:all, _format: ~ } requirements: _method: GET acme_demo_user_get: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:get, _format: ~ } requirements: _method: GET id: "\d+" 

UserController वर्ग में निम्नलिखित कोड शामिल होंगे:

 <?php namespace Acme\DemoBundle\Controller; use Acme\DemoBundle\Model\User; use Acme\DemoBundle\Model\UserQuery; use FOS\RestBundle\Controller\Annotations as Rest; use Symfony\Component\HttpKernel\Exception\NotFoundHttpException; class UserController { /** * @Rest\View */ public function allAction() { $users = UserQuery::create()->find(); return array('users' => $users); } /** * @Rest\View */ public function getAction($id) { $user = UserQuery::create()->findPk($id); if (!$user instanceof User) { throw new NotFoundHttpException('User not found'); } return array('user' => $user); } } 

* * () विधियों में पैरामीटर कनवर्टर का उपयोग करने के बजाय, मुझे हमेशा वस्तुओं को स्वयं प्राप्त करना होगा। बाद में मैं समझाता हूँ कि क्यों, लेकिन अभी के लिए, बस मुझ पर विश्वास करो, यह वास्तव में बेहतर है।

ग्राहकों के लिए स्थिति कोड महत्वपूर्ण है, इसलिए यदि उपयोगकर्ता मौजूद नहीं है, तो NotFoundHttpException अपवाद का उपयोग करें, जो स्थिति कोड 404 के साथ प्रतिक्रिया लौटाएगा।

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

और अंत में, AllAction () विधि। यह getAction के समान व्यवहार करता है: आपको केवल उपयोगकर्ताओं का चयन मिलता है और इसे वापस करना होता है।

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

 # In Propel, the most part of the code is located in base classes # src/Acme/DemoBundle/Resources/config/serializer/Model.om.BaseUser.yml Acme\DemoBundle\Model\om\BaseUser: exclusion_policy: ALL properties: id: expose: true username: expose: true email: expose: true 

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

परिणामस्वरूप, हमें निम्नलिखित JSON प्रतिक्रिया मिलती है:

 { "user": { "id": 999, "username": "xxxx", "email": "xxxx@example.org" } } 

सरल, सही? लेकिन आपको संभवतः उपयोगकर्ताओं को बनाने, संशोधित करने या हटाने की आवश्यकता होगी, और यह अगले अध्याय के लिए विषय होगा।

इसे पोस्ट करें

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

आप क्रमांकित इनपुट से एक फॉर्म ऑब्जेक्ट बनाने के लिए डीसेरिएलाइज़ेशन तंत्र का उपयोग कर सकते हैं। बेंजामिन नाम का एक लड़का एक फॉर्म डेजिलाइज़र पर काम करता है। यह विधि Serializer घटक का उपयोग करने से केवल थोड़ा अलग है, लेकिन यह सरल लगता है।

मैं सिम्फनी से कूल फॉर्म घटक का उपयोग एक ही बार में करने के लिए करता हूं। एक नया उपयोगकर्ता बनाने के लिए एक फार्म वर्ग लिखें। PropelBundle का उपयोग करके आप प्रोपेल का उपयोग कर सकते हैं : फ़ॉर्म: कमांड कमांड उत्पन्न करें :

 php app/console propel:form:generate @AcmeDemoBundle User 

यह कमांड निम्नलिखित फॉर्म क्लास बनाएगी:

 <?php namespace Acme\DemoBundle\Form\Type; use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolverInterface; class UserType extends AbstractType { /** * {@inheritdoc} */ public function buildForm(FormBuilderInterface $builder, array $options) { $builder->add('username'); $builder->add('email', 'email'); $builder->add('password', 'password'); } /** * {@inheritdoc} */ public function setDefaultOptions(OptionsResolverInterface $resolver) { $resolver->setDefaults(array( 'data_class' => 'Acme\DemoBundle\Model\User', 'csrf_protection' => false, )); } /** * {@inheritdoc} */ public function getName() { return 'user'; } } 

मुझे अपने हाथों से कुछ करना था: ईमेल और पासवर्ड प्रकार, और मैंने सीएसआरएफ सुरक्षा भी बंद कर दी। REST API में, आप सबसे अधिक सुरक्षा परत का उपयोग करते हैं, जैसे OAuth। एक REST संदर्भ में CSRF सुरक्षा होने से कोई मतलब नहीं है।

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

हमारे मामले में लौटकर, मैं YAML में सत्यापन नियमों का वर्णन करने के लिए उपयोग किया गया था, लेकिन कोई भी आपको अपनी पसंद में प्रतिबंधित नहीं करता है। यहाँ एक उदाहरण है:

 # src/Acme/DemoBundle/Resources/config/validation.yml Acme\DemoBundle\Model\User: getters: username: - NotBlank: email: - NotBlank: - Email: password: - NotBlank: 

आइए अब कंट्रोलर में एक विधि लिखते हैं:

 <?php // ... public function newAction() { return $this->processForm(new User()); } 

एक और टिप। अपने प्रपत्रों को संसाधित करने के लिए हमेशा एक अलग विधि का उपयोग करें। तब आप खुद को धन्यवाद दें। ProcessForm () विधि कुछ इस तरह दिखती है:

 // ... private function processForm(User $user) { $statusCode = $user->isNew() ? 201 : 204; $form = $this->createForm(new UserType(), $user); $form->bind($this->getRequest()); if ($form->isValid()) { $user->save(); $response = new Response(); $response->setStatusCode($statusCode); $response->headers->set('Location', $this->generateUrl( 'acme_demo_user_get', array('id' => $user->getId()), true // absolute ) ); return $response; } return View::create($form, 400); } 

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

 { "children": { "username": { "errors": [ "This value should not be blank." ] } } } 

नोट: यहां जो दृश्य वर्ग हम देखते हैं, वही नहीं है जो हम एनोटेशन में उपयोग करते हैं, यही कारण है कि मैंने उनके लिए एक उपनाम का उपयोग किया है। FOSRestBundle प्रलेखन में "दृश्य परत" अध्याय में इस वर्ग के बारे में और पढ़ें।

फॉर्म के नाम को पास करने के लिए भी यह महत्वपूर्ण है। आमतौर पर, ग्राहक आपको कुछ इस तरह से भेजेंगे:

 { "user": { "username": "foo", "email": "foo@example.org", "password": "hahaha" } } 

आप इस विधि को कर्ल के साथ कॉल करने का प्रयास कर सकते हैं:

 curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"user":{"username":"foo", "email": "foo@example.org", "password": "hahaha"}}' http://example.com/users 

सुनिश्चित करें कि आपने FOSRestBundle सेटिंग में body_listener पैरामीटर के लिए सही सेट किया है। यह पैरामीटर आपको JSON, XML और अन्य के प्रारूप में डेटा प्राप्त करने की अनुमति देता है। फिर से, सब कुछ बॉक्स से बाहर काम करता है।

जैसा कि मैंने पहले कहा था, अगर सब कुछ ठीक हो जाता है, तो आप अपने उपयोगकर्ता ($ उपयोगकर्ता-> प्रोपेल में सहेजें) को बचाते हैं और फिर जवाब वापस करते हैं।

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

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

जानते हो क्या? मैं मैनिक दृष्टिकोण पसंद करता हूं, और मैं विनिर्देशन का पालन करता हूं, केवल स्थान हेडर लौटाता हूं:

 Location: http://example.com/users/999 

यदि मैं एक ग्राहक के रूप में जावास्क्रिप्ट फ्रेमवर्क Backbone.js का उपयोग करता हूं, क्योंकि मैं इसके कुछ हिस्सों को फिर से लिखना नहीं चाहता हूं क्योंकि यह सही एपीआई का समर्थन नहीं करता है, तो मैं सब कुछ के अलावा आईडी वापस कर दूंगा। व्यावहारिक होना अभी भी इतना बुरा नहीं है।

इस क्रिया के लिए रूटिंग नियम जोड़ना याद रखें। संसाधन बनाना संग्रह के लिए एक POST अनुरोध है, इसलिए एक नया नियम जोड़ें:

 acme_demo_user_new: pattern: /users defaults: { _controller: AcmeDemoBundle:User:new, _format: ~ } requirements: _method: POST 

एक नया संसाधन बनाने का तरीका जानने के बाद, इसे बदलना काफी आसान होगा।

पैट बनाम पिच, लड़ाई!

संसाधन बदलने का अर्थ है कि इसे बदलना, खासकर यदि आप HTTP PUT विधि का उपयोग करते हैं। एक PATCH विधि भी है जो संसाधनों के बीच का अंतर लेती है और पैच को मूल संसाधन पर लागू करती है, दूसरे शब्दों में, आंशिक अद्यतन करती है।

पहले किए गए कार्यों के लिए धन्यवाद, संसाधन को बदलना काफी आसान होगा। आपको नियंत्रक में एक नई विधि लिखनी होगी और एक नया रूटिंग नियम जोड़ना होगा। यहां हम अपने उपयोगकर्ता की वस्तु प्राप्त करने के लिए एक पैरामीटर कनवर्टर पर भरोसा कर सकते हैं। यदि ऐसा उपयोगकर्ता मौजूद नहीं है, तो पैरामीटर कनवर्टर एक अपवाद फेंक देगा और यह अपवाद स्थिति कोड 404 के साथ प्रतिक्रिया में परिवर्तित हो जाएगा।

 <?php // ... public function editAction(User $user) { return $this->processForm($user); } 

संसाधन बदलने का अर्थ है कि आप पहले से ही इसके बारे में सब कुछ जानते हैं, ताकि आप इस संसाधन के लिए केवल URI के PUT अनुरोध में वापस लौट सकें:

 acme_demo_user_edit: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:edit, _format: ~ } requirements: _method: PUT 

और वह सब है! एक संसाधन को हटाने के बारे में क्या?

हटाएँ

एक संसाधन निकालना बहुत सरल है। एक रूटिंग नियम जोड़ें:

 acme_demo_user_delete: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:remove, _format: ~ } requirements: _method: DELETE 

और एक छोटी विधि लिखें:

 <?php // ... /** * @Rest\View(statusCode=204) */ public function removeAction(User $user) { $user->delete(); } 

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

REST के माध्यम से किसी दिए गए उपयोगकर्ता के लिए एक मित्र सूची कैसे प्राप्त करें? हमें केवल दोस्तों को किसी विशेष उपयोगकर्ता से संबंधित उपयोगकर्ताओं के संग्रह के रूप में विचार करने की आवश्यकता है। आइए इस इंटरैक्शन को लागू करें।

मित्रता एल्गोरिथ्म

सबसे पहले, हमें एक नया रूटिंग नियम बनाने की आवश्यकता है। चूँकि हम मित्रों को उपयोगकर्ताओं का संग्रह मानते हैं, इसलिए हम इसे सीधे संसाधन से प्राप्त करेंगे:

 acme_demo_user_get_friends: pattern: /users/{id}/friends defaults: { _controller: AcmeDemoBundle:User:getFriends, _format: ~ } requirements: _method: GET 

यह क्रिया नियंत्रक में इस तरह दिखाई देगी:

 <?php // ... public function getFriendsAction(User $user) { return array('friends' => $user->getFriends()); } 

वह सब है। अब आइए विचार करें कि किसी अन्य उपयोगकर्ता के दोस्त बनने की प्रक्रिया का वर्णन कैसे करें। आप इसे REST के माध्यम से कैसे प्रबंधित करेंगे? आप दोस्तों के एक संग्रह के लिए POST का उपयोग नहीं कर सकते क्योंकि आप कुछ भी बनाने नहीं जा रहे हैं। दोनों उपयोगकर्ता पहले से मौजूद हैं। आप PUT पद्धति का उपयोग नहीं कर सकते क्योंकि आप वास्तव में संपूर्ण संग्रह को बदलना नहीं चाहते हैं। यह वास्तव में हमें चकित कर सकता है ...

लेकिन, HTTP प्रोटोकॉल विनिर्देश एक लिंक विधि का वर्णन करता है जो हमारी समस्या को हल करता है। यह कहता है:

लिंक विधि अनुरोध-यूआरआई और अन्य मौजूदा संसाधनों में निर्दिष्ट मौजूदा संसाधन के बीच एक या एक से अधिक संबंध स्थापित करती है।

यह वही है जो हमें चाहिए। हम दो संसाधनों को जोड़ना चाहते हैं, हमें एपीआई सेवाओं को लिखते समय संसाधनों के बारे में नहीं भूलना चाहिए। तो सिम्फनी 2 में यह कैसे करें?

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

 LINK /users/1 Link: <http://example.com/users/2>; rel="friend" Link: <http://example.com/users/3>; rel="friend" 

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

अनुरोध श्रोता इन सभी लिंक हेडर को ले जाएगा और उन्हें नियंत्रक और विधि के नाम प्राप्त करने के लिए Symfony2 RouterMatcher घटक के लिए उपयोग करेगा। वह मापदंडों को भी तैयार करेगा।

दूसरे शब्दों में, नियंत्रक बनाने और आवश्यक मापदंडों के साथ इसमें सही विधि को कॉल करने के लिए सभी आवश्यक जानकारी है। हमारे उदाहरण में, UserController में getUser () विधि को प्रत्येक लिंक हेडर के लिए बुलाया जाएगा। यही कारण है कि मैंने पैरामीटर कनवर्टर का उपयोग नहीं किया, इससे मुझे तर्क के मूल्य के रूप में आईडी लेने की अनुमति मिली, ताकि मुझे इसके लिए एक संसाधन मिल सके। मैंने कुछ धारणाएँ बनाईं:

• यदि उपयोगकर्ता मौजूद नहीं है, तो एक अपवाद मुझे वापस कर दिया जाएगा;
• व्यू एनोटेशन का उपयोग करने के बाद से मुझे रिटर्न वैल्यू के रूप में एरे मिलेगा।

जब मुझे अपने संसाधन ऑब्जेक्ट मिलते हैं, तो मैं उन्हें अनुरोध विशेषताओं के रूप में रखूंगा, और हमारे श्रोता के लिए, काम पूरा हो जाएगा। यहाँ कोड है:

 <?php namespace Acme\DemoBundle\EventListener; use Symfony\Component\HttpKernel\Event\GetResponseEvent; use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface; use Symfony\Component\Routing\Matcher\UrlMatcherInterface; use Symfony\Component\HttpFoundation\Request; class LinkRequestListener { /** * @var ControllerResolverInterface */ private $resolver; private $urlMatcher; /** * @param ControllerResolverInterface $controllerResolver The 'controller_resolver' service * @param UrlMatcherInterface $urlMatcher The 'router' service */ public function __construct(ControllerResolverInterface $controllerResolver, UrlMatcherInterface $urlMatcher) { $this->resolver = $controllerResolver; $this->urlMatcher = $urlMatcher; } public function onKernelRequest(GetResponseEvent $event) { if (!$event->getRequest()->headers->has('link')) { return; } $links = array(); $header = $event->getRequest()->headers->get('link'); /* *   ,     *     . * *         Link   * http://tools.ietf.org/html/rfc2068#section-19.6.2.4 */ while (preg_match('/^((?:[^"]|"[^"]*")*?),/', $header, $matches)) { $header = trim(substr($header, strlen($matches[0]))); $links[] = $matches[1]; } if ($header) { $links[] = $header; } $requestMethod = $this->urlMatcher->getContext()->getMethod(); //    GET    //     ,      (LINK/UNLINK) $this->urlMatcher->getContext()->setMethod('GET'); //           $stubRequest = new Request(); foreach ($links as $idx => $link) { $linkParams = explode(';', trim($link)); $resource = array_shift($linkParams); $resource = preg_replace('/<|>/', '', $resource); try { $route = $this->urlMatcher->match($resource); } catch (\Exception $e) { //        //     Link continue; } $stubRequest->attributes->replace($route); if (false === $controller = $this->resolver->getController($stubRequest)) { continue; } $arguments = $this->resolver->getArguments($stubRequest, $controller); try { $result = call_user_func_array($controller, $arguments); //       if (!is_array($result)) { continue; } //     $links[$idx] = current($result); } catch (\Exception $e) { continue; } } $event->getRequest()->attributes->set('link', $links); $this->urlMatcher->getContext()->setMethod($requestMethod); } } 

अब हम एक रूटिंग नियम बना सकते हैं:

 acme_demo_user_link: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:link, _format: ~ } requirements: _method: LINK 

और हमारी कार्रवाई का कोड इस तरह दिखेगा:

 <?php // ... /** * @Rest\View(statusCode=204) */ public function linkAction(User $user, Request $request) { if (!$request->attributes->has('link')) { throw new HttpException(400); } foreach ($request->headers->get('Link') as $u) { if (!$u instanceof User) { throw new NotFoundHttpException('Invalid resource'); } if ($user->hasFriend($u)) { throw new HttpException(409, 'Users are already friends'); } $user->addFriend($u); } $user->save(); } 

यदि उपयोगकर्ता पहले से ही मित्र हैं, तो हमें 409 की स्थिति कोड के साथ प्रतिक्रिया मिलेगी, जिसका अर्थ है कि एक संघर्ष हुआ है। यदि अनुरोध लिंक हेडर को याद कर रहा है, तो यह खराब अनुरोध (400) है।

वही दोस्तों को हटाने के लिए जाता है। केवल यहाँ हम UNLINK विधि का उपयोग करेंगे।

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

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

हम PATCH की दुनिया पर थोपते हैं

सबसे पहले, एक नया रूटिंग नियम परिभाषित करें:

 acme_demo_user_patch: pattern: /users/{id} defaults: { _controller: AcmeDemoBundle:User:patch, _format: ~ } requirements: _method: PATCH 

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

चलो इनपुट मापदंडों को फ़िल्टर करते हैं:

 <?php $parameters = array(); foreach ($request->request->all() as $k => $v) { //   if (in_array($k, array('email'))) { $parameters[$k] = $v; } } 

जैसे ही हमने आने वाले मापदंडों को फ़िल्टर किया, हमें बिल्कुल वही पैरामीटर मिले जो हम चाहते थे। यदि हमें कुछ भी नहीं मिला है, तो यह एक बुरा अनुरोध है और हमें 400 की स्थिति कोड के साथ प्रतिक्रिया वापस करनी चाहिए।

यदि सब ठीक है, तो हम संसाधन को नए मान दे सकते हैं। ओह रुको ... नहीं! हमें पहले इकाई की जांच करनी चाहिए और केवल तभी जब सभी डेटा मान्य हों, इसे सहेजें।

इस क्रिया का कोड कुछ इस प्रकार होगा:

 <?php // .... public function patchAction(User $user, Request $request) { $parameters = array(); foreach ($request->request->all() as $k => $v) { // whitelist if (in_array($k, array('email'))) { $parameters[$k] = $v; } } if (0 === count($parameters)) { return View::create( array('errors' => array('Invalid parameters.')), 400 ); } $user->fromArray($parameters); $errors = $this->get('validator')->validate($user); if (0 < count($errors)) { return View::create(array('errors' => $errors), 400); } $user->save(); $response = new Response(); $response->setStatusCode(204); $response->headers->set('Location', $this->generateUrl( 'acme_demo_user_get', array('id' => $user->getId()), true // absolute ) ); return $response; } 

कोड बहुत सरल है, है ना? हमेशा की तरह, जब आप कोई संसाधन बनाते हैं या अपडेट करते हैं, तो आपको एक 2xx स्थिति कोड और एक स्थान हेडर के साथ प्रतिक्रिया भेजनी चाहिए। यहां हम कोड 204 भेजते हैं क्योंकि यहां कोई सामग्री नहीं है और हम कुछ भी नहीं बना रहे हैं।

और अब, क्या योजना है? हमने पहले से ही GET, POST, PUT, DELETE, PATCH, LINK और UNLINK तरीकों का इस्तेमाल किया है । हम उपयोगकर्ताओं को आंशिक रूप से अपडेट कर सकते हैं, प्राप्त कर सकते हैं, संशोधित कर सकते हैं, हटा सकते हैं। हम सभी उपयोगकर्ताओं की सूची प्राप्त कर सकते हैं और उनके बीच मित्रता स्थापित कर सकते हैं। हम जानते हैं कि यदि हमें उपयोगकर्ता डेटा को बदलने की आवश्यकता है, तो हम सुरक्षित रूप से पाथ विधि का उपयोग कर सकते हैं।

वास्तव में, रिचर्डसन परिपक्वता मॉडल के बारे में , हमने केवल दूसरे स्तर को कवर किया। तो चलिए HATEOAS पर एक नज़र डालते हैं और तीसरे स्तर को अनलॉक करते हैं!

किससे घृणा करनी है?

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

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

हम अपने उपयोगकर्ता के प्रतिनिधित्व को XML में बदलते हैं:

 <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> </user> 

यदि क्लाइंट XML से अनुरोध करता है तो यह आपकी प्राप्त विधि का आउटपुट है। HATEOAS से कुछ भी नहीं है। पहला चरण लिंक जोड़ना है:

 <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> <link href="http://example.com/users/999" rel="self" /> </user> 

यह सरल था, हमने सिर्फ एक लिंक जोड़ा, जो उस उपयोगकर्ता को संदर्भित करता है जिसका डेटा हमें प्राप्त हुआ था। लेकिन यदि आपका उपयोगकर्ता संग्रह पृष्ठांकित है, तो आप निम्नलिखित प्राप्त कर सकते हैं:

 <users> <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> <link href="http://example.com/users/999" rel="self" /> <link href="http://example.com/users/999/friends" rel="friends" /> </user> <user> <id>123</id> <username>foobar</username> <email>foobar@example.org</email> <link href="http://example.com/users/123" rel="self" /> <link href="http://example.com/users/123/friends" rel="friends" /> </user> <link href="http://example.com/users?page=1" rel="prev" /> <link href="http://example.com/users?page=2" rel="self" /> <link href="http://example.com/users?page=3" rel="next" /> </users> 

अब क्लाइंट को पता है कि संग्रह को कैसे देखना है, पृष्ठों को कैसे नेविगेट करना है और उपयोगकर्ता और / या उसके दोस्तों को कैसे प्राप्त करना है।

अगला कदम सवाल के जवाब के रूप में मीडिया प्रकारों को जोड़ना है : क्या? एक संसाधन क्या है? इसमें क्या शामिल है या मुझे ऐसा संसाधन बनाने की क्या आवश्यकता है?

यह भाग आपको अपनी सामग्री प्रकार से परिचित कराएगा:

 Content-Type: application/vnd.yourname.something+xml 

हमारे उपयोगकर्ता अब निम्न प्रकार की सामग्री का उल्लेख करते हैं: एप्लिकेशन / vnd.acme.user + xml।

 <user> <id>999</id> <username>xxxx</username> <email>xxxx@example.org</email> <link href="http://example.com/users/999" rel="self" /> <link rel="friends" type="application/vnd.acme.user+xml" href="http://example.com/users/999/friends" /> </user> 

अंतिम लेकिन कम से कम, आप तीन अलग-अलग तरीकों से अपनी एपीआई सेवा में संस्करण जोड़ सकते हैं। अपने यूआरआई में संस्करण संख्या जोड़ने का एक आसान तरीका होगा:

 /api/v1/users 

दूसरा तरीका यह है कि एक नई सामग्री प्रकार घोषित करें:

 application/vnd.acme.user-v1+xml 

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

 application/vnd.acme.user+xml;v=1 

आप चुनें कि किस तरीके का उपयोग करना है। पहली विधि सबसे आसान है, लेकिन यह अन्य दो की तुलना में कम Restful भी है। सच है, अन्य दो को होशियार ग्राहकों की जरूरत है।

परीक्षण

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

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

 $client = static::createClient(); $crawler = $client->request('GET', '/users'); $response = $this->client->getResponse(); $this->assertJsonResponse($response, 200); 

मैं अपने WebTestCase क्लास का उपयोग करता हूं जिसमें मैंने assertJsonResponse () विधि लागू की है:

 <?php // ... protected function assertJsonResponse($response, $statusCode = 200) { $this->assertEquals( $statusCode, $response->getStatusCode(), $response->getContent() ); $this->assertTrue( $response->headers->contains('Content-Type', 'application/json'), $response->headers ); } 

यह पहला सत्यापन कदम है जो एपीआई कॉल के तुरंत बाद चलता है। यदि सब कुछ ठीक रहा, तो मैं अन्य जांच करता हूं जो पहले से ही मेरे द्वारा प्राप्त डेटा से संबंधित हैं।

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

प्रलेखन

अच्छा एपीआई प्रलेखन एक बहुत ही महत्वपूर्ण पैरामीटर है क्योंकि यह एकमात्र ऐसी चीज है जिसका ग्राहकों तक पहुंच होगी। आप उन्हें सभी कोड प्रदान नहीं करेंगे?

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

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

लेकिन यहाँ बचाव के लिए NelmioApiDocBundle आता है। मैंने यह बंडल Nelmio में लिखा थास्वचालित रूप से हमारे एपीआई सेवाओं के लिए प्रलेखन उत्पन्न करने के लिए। कोड के आत्मनिरीक्षण के आधार पर, बंडल को कई अलग-अलग जानकारी मिलती है, और इसे अच्छी तरह से डिज़ाइन किए गए पृष्ठों पर प्रदर्शित करता है।




अब आपके पास महान एपीआई सेवाओं के निर्माण के लिए सब कुछ है।

उपयोगी लिंक

• RFC 2616 - धारा 10 - स्टेटस कोड का विवरण;
• RFC 2068 - धारा 19.6 - अतिरिक्त सुविधाएँ
• RFC 5988 - वेब लिंकिंग।

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