How to Design REST API? Written Date : March 23, 2015

Transcription

1 Visul Prdigm How Design REST API? Turil How Design REST API? Written Dte : Mrch 23, 2015 REpresenttionl Stte Trnsfer, n rchitecturl style tht cn be used in building networked pplictions, is becoming incresingly populr nowdys. Mny leding vendors hve opened doors of ir services developers, providing m with restful ccesses different web services. This turil shows how design REST API with Visul Prdigm. The genertion of API (code nd librry) nd API documenttion will lso be covered. In this turil, we will use simple membership registrtion service s n exmple show how design REST API for such service. Designing REST API 1. The design of REST API hs done in Clss Digrm. To crete Clss Digrm, select Digrm > New from olbr. 2. In New Digrm window, select Clss Digrm nd click Next. Pge 1 of 15

2 Visul Prdigm How Design REST API? Turil 3. Enter Membership Registrtion API Design s digrm nme. 4. Click OK confirm. 5. Select REST Resource in digrm olbr. 6. Click on digrm crete REST Resource nd nme it Members. A REST resource is fundmentl unit of n API tht conforms REST, which is wht we clled REST API. It is n object with URI, http request method, ssocited prmeters nd request/response body. Ech of REST resources represents specific service vilble on pth specified by its URI property. Therefore, if you wnt model multiple services, plese drw multiple REST resources 7. Right click on Members REST Resource nd select Open Specifiction... from popup menu. 8. In Generl tb, fill in following: Pge 2 of 15

3 Visul Prdigm How Design REST API? Turil Field Vlue Remrks URI /members Ech REST hs its own URI. ccess URL ccess for REST Typiclly, RESTful URI should refer resource tht is thing insted of referring n ction. when you re deciding URI, try use Pge 3 of 15

4 Visul Prdigm How Design REST API? Turil noun insted of verb. Method POST Specifies ction ct on resource. GET - A GET method (or GET request) is used retrieve of resource. It should be used SOLELY for retrieving dt nd should not lter. PUT - A PUT method (or PUT Pge 4 of 15

5 request) is used updte resource. For instnce, if you know tht blog post resides t blogs/123 you cn updte this specific post by using PUT method put new resource represent of post. POST - A POST method (or POST request) Visul Prdigm How Design REST API? Turil Pge 5 of 15

6 Visul Prdigm How Design REST API? Turil is used crete resource. For instnce, when you wnt dd new blog post but hve no ide where sre it, you cn use POST method post it URL nd let server decide URL. DELETE - A DELETE method Pge 6 of 15

7 Visul Prdigm How Design REST API? Turil (or DELETE request) is used delete resource identified by URI. Description Crete new member by providing his/her nme, ddress nd telephone number. You will receive n object tht holds nme, ddress, telephone nd member ID of member. Descriptio of resource tht will pper in generted API document It is recommen provide cler descriptio of service, so tht consumer know wht service is nd how operte with it. Pge 7 of 15

8 Visul Prdigm How Design REST API? Turil 9. Click OK. 10. Let's sy membership registrtion requires users provide informtion like nme, ddress nd telephone. In API level, se re prmeters required by service nd should be provided by consumer of service. Let's represent this in our design. Move your mouse pointer over REST Request Body icon nd drg out Resource Ctlog butn t p right. 11. Relese mouse butn nd select Assocition -> One Clss from Resource Ctlog. 12. Nme clss Member. Pge 8 of 15

9 Visul Prdigm How Design REST API? Turil 13. Add three String ttributes in Member clss s prmeters - nme, ddress nd telephone. 14. Enter description of three ttributes. You cn enter description in description edir or in ttribute specifiction window (Right click on n ttribute nd select Open Specifiction... from popup menu). The description entered will be presented in API documenttion. Attribute nme ddress Description The full nme of member. The residentil ddress of member. telephone The telephone number of member. Tht's ll for request prt. You re free crete more complex structure by creting more ssocited clsses, but normlly you don't need do this. Now, let's move on response prt. Pge 9 of 15

10 Visul Prdigm How Design REST API? Turil 15. Vlue(s) be returned by server, if ny, is modeled vi Response Body. Let's sy member ID will be returned by server upon cretion of membership. Move your mouse pointer over REST Response Body icon nd drg out Resource Ctlog butn t p right. 16. Relese mouse butn nd select Assocition -> One Clss from Resource Ctlog. Note: If service will return n rry of objects, select Assocition -> Mny Clss insted. 17. Nme clss MemberID. Pge 10 of 15

11 Visul Prdigm How Design REST API? Turil 18. Add String ttribute vlue. 19. Enter description of vlue ttribute: The member ID. Specifying Request nd Response Heder nd Exmple A HTTP messge consists of HTTP request line, collection of heder fields nd n optionl body. In order for consumers ccess REST Resource, you hve specify request heders nd request (body) exmple. The request heder nd exmple specified will be presented in generted API documenttion. Consumer cn n follow documenttion in using API. 1. Right click on Members REST Resource nd select Open Specifiction... from popup menu. 2. Open Request Body tb. 3. Enter Heder: content-type: ppliction/ json uthoriztion: Berer myken Enter Exmple in JSON: { "nme" : "Peter", "ddress" : "100, Hppy Vlley", "telephone" : " " } Pge 11 of 15

12 Visul Prdigm How Design REST API? Turil 5. Open Response Body tb. 6. Enter Heder: content-type: ppliction/json; chrset=utf-8 sttus: 200 OK rtelimit-limit: 1200 rtelimit-remining: 1137 rtelimit-reset: Enter Exmple in JSON: { "MemberID": { "vlue": "MB-3001" } } Pge 12 of 15

13 Visul Prdigm How Design REST API? Turil 8. Click OK confirm chnges. Generting REST API nd API Documenttion Once you hve finished design of your REST APIs, you cn generte API nd API documenttion. 1. Select Tools > Code > Generte REST API... from olbr. 2. In REST API window, keep Provider selected for API Type. By doing so, you will be ble generte API documenttion s well s server smple code tht guides you in progrmming your service (logic). 3. Check Members resource generte API. 4. Check Generte API Documenttion generte HTML files tht shows how use selected REST Resource(s). Supposedly, you will publish generted API documenttion in your website, so tht consumers of your service cn red through it know how ccess use your APIs. 5. Enter your compny nme, which will be presented in API documenttion. 6. Enter bse URL of your services. 7. Check Generte Smple generte source code tht teches you how progrm your API. The smple code is rich nd informtive. Therefore, insted of progrmming from scrtch, we strongly recommend you generte smple code nd modify its content fit your needs. Pge 13 of 15

14 Visul Prdigm How Design REST API? Turil 8. Enter output pth of code. 9. Click Generte. The following folders re generted in output direcry. Folder doc lib Description The API documenttion. You should publish API documenttion in your website, so tht consumers of your service cn check documenttion lern API. In order for generted code work, Google Gson librry must be presented in your clss pth. To void ny comptibility issues, plese downlod librry mnully: nd n plce file in lib folder. smple_srcthe smple code of client nd servlet. It shows you how ccess s client nd how rect request s provider. We strongly recommend you copy code nd modify it by filling in your own service logic. src The source code of communiction model. Do not modify file content or else code my not be ble function properly. Pge 14 of 15

15 Visul Prdigm How Design REST API? Turil 10. Open generted API documenttion nd tke look. The design (imge), description of prmeters, request nd response heder nd exmple re presented in document. Resources 1. Downlod REST API Exmple - Simple Registrtion Service.vpp Visul Prdigm home pge ( Visul Prdigm turils ( Pge 15 of 15