Preparing a REST API. Rules of REST APIs, API patterns, Typical CRUD operations

Size: px

Start display at page:

Download "Preparing a REST API. Rules of REST APIs, API patterns, Typical CRUD operations"

Clemence Richardson
6 years ago
Views:

1 Preparing a REST API Rules f REST APIs, API patterns, Typical CRUD peratins

2 Rules fr a REST API Recall: REST Representatinal State Transfer REST is stateless it has n idea f any current user state r histry API Applicatin Prgramming Interface REST API stateless interface t yur applicatin Standards: REST APIs have an assciated set f standards Generally best t stick t them Yu re ding things the right way if yu decide t make yur API public

Request URLs Request URLs fr a REST API have a simple standard Think abut yur DB cllectins Will typically have a set f URLs fr each cllectin May als have a set f URLs fr each set f

4 Request URLs Request URLs fr a REST API have a simple standard Think abut yur DB cllectins Will typically have a set f URLs fr each cllectin May als have a set f URLs fr each set f subdcuments Each URL in a set will have the same basic path, and sme may have additinal parameters Within a set f URLs yu need t cver a number f actins, generally based arund the standard CRUD peratins

5 Cmmn actins Create a new item Read a list f several items Read a specific item Update a specific item Delete a specific item

URL paths and params fr an API Actin URL path Parameters Example Create new cntact /cntacts /api/cntacts Read list f cntact /cntacts /api/cntacts Read specific

6 URL paths and params fr an API Actin URL path Parameters Example Create new cntact /cntacts /api/cntacts Read list f cntact /cntacts /api/cntacts Read specific cntact /cntacts cntactid /api/cntacts/123abc Update specific cntact /cntacts cntactid /api/cntacts/123abc Delete specific cntact /cntacts cntactid /api/cntacts/123abc

7 Request methds used in a REST API Request methd Use Respnse GET Read data frm DB Data bject answering request POST Create new data in DB New data bject as seen in DB PUT Update a dc in DB Updated data bject as seen in DB DELETE Delete an bject frm DB Null

8 Request methd links URL t desired actin Actin Methd URL path Parameters Example Create new cntact POST /cntacts /api/cntacts Read list f cntact GET /cntacts /api/cntacts Read specific cntact GET /cntacts cntactid /api/cntacts/123abc Update specific cntact PUT /cntacts cntactid /api/cntacts/123abc Delete specific cntact DELETE /cntacts cntactid /api/cntacts/123abc

9 API URLs fr subdcuments Subdcuments are treated in a similar way, but require an additinal parameter E.g.: Actin: Create a new review fr a prduct Methd: POST URL path: /prducts/prductid/reviews/reviewid Parameters: prductid, reviewid URL: /api/prducts/123/reviews/abd

Respnses and status cde If yu make a request, a gd API will always respnd and nt leave yu hanging Every single API request shuld return a respnse Fr a successful

10 Respnses and status cde If yu make a request, a gd API will always respnd and nt leave yu hanging Every single API request shuld return a respnse Fr a successful REST API, standardizing the respnses is just as imprtant as standardizing the request frmat. There are tw key cmpnents t a respnse: The returned data The HTTP status cde

11 Returning data frm an API Yur API shuld return a cnsistent data frmat Typical frmats fr a REST API are XML and JSON Our API will return ne f three things fr each request: A JSON bject cntaining data answering the request query A JSON bject cntaining errr data A null respnse

12 10 Mst ppular status cdes A gd REST API shuld return the crrect HTTP status cde Status Cde Name Use case 200 OK A successful GET r PUT request 201 Created A successful POST request 204 N Cntent A successful DELETE request 400 Bad Request n unsuccessful GET, PUT, r POST request due t invalid cntent 401 Unauthrized Requesting a restricted URL with invalid credentials 403 Frbidden Making a request that isn't allwed 404 Nt Fund Unsuccessful request due t invalid parameter in URL 405 Methd nt allwed Request methd nt allwed fr given URL 409 Cnflict Unsuccessful POST request when anther bject with the same data already exists 500 Internal server errr Prblem with the server r DB server

13 Setting up API in express We ve already gt a gd idea abut the actins we want ur API t perfrm, and the URL paths needed t d s We need t setup cntrllers and rutes t cause express t d smething with an incming URL Cntrllers will d the actins Rutes will map incming requests t apprpriate cntrllers Need t require the rutes in app.js Need t tell applicatin when t use the rutes Define actins in the cntrllers

14 Next steps Either in the rutes r cntrllers file, specify the fllwing: The request methd The required URL parameters The definitin f the full API rutes In cntrller: Return JSON and respnse status cde frm an Express request Use Mngse mdel t read data frm mngdb Use Pstman REST client t test requests t the API

15 Reading data frm MngDB Mngse mdels have several methds available t them t help with querying the database. Here are sme f the key nes: find - General search based n a supplied query bject findbyid - Lk fr a specific ID findone - Get the first dcument t match the supplied query It s gd t run query with exec() Be sure t catch errrs and return apprpriate respnse

16 Limiting return paths Limiting the data being passed arund is better fr bandwidth cnsumptin and speed Mngse des this thrugh a select methd chained t the mdel query Prduct.findById(req.params.prductid).select('name reviews').exec( functin(err, prduct) { // d errr checking-prduct var review; review = prduct.reviews.id(req.params.reviewid); // d errr checking fr review } );

17 Resurces Getting MEAN with Mng, Express, Angular, and Nde Simn Hlmes Nvember 2015 ISBN pages printed in black & white

DICOM Correction Proposal

DICOM Correction Proposal DICOM Crrectin Prpsal STATUS Final Text Date f Last Update 2014/06/25 Persn Assigned Submitter Name James Philbin Jnathan Whitby (jwhitby@vitalimages.cm) Submissin Date 2013/10/17 Crrectin Number CP-1351