SlideShare a Scribd company logo

REST-API introduction for developers

•Download as PPTX, PDF•
•
Patrick Savalle
Patrick Savalle

Simple REST-API overview for developers. An newer version is here: https://www.slideshare.net/patricksavalle/super-simple-introduction-to-restapis-2nd-version-127968966

Related slideshows

Learn REST in 18 Slides
Learn REST in 18 SlidesLearn REST in 18 Slides
Learn REST in 18 Slides
 
Rest api standards and best practices
Rest api standards and best practicesRest api standards and best practices
Rest api standards and best practices
 
An Introduction To REST API
An Introduction To REST APIAn Introduction To REST API
An Introduction To REST API
 
1 of 25
Super simple introduction to REST-API’s For programmers By Patrick Savalle, innovation architect Delta Lloyd NV.
REST-API introduction for developers
CONTENTS 1. HTTP-BASICS 2. REST-BASICS 3. API-BASICS
PART 1 HTTP BASICS
REST is HTTP/1.1. It is the native protocol of the web. Advantages are: • Every tool that can handle Web / HTTP, can handle REST as native ‘content’. For instance gateways, web-servers and browsers can effectively cache, route, verify, manipulate REST requests or responses. • In short the whole web supports REST • It is simple and elegant • Less diversity in technology, you already use HTTP Part1:~ Http$ WHY REST?_ REST is HTTP. It is the same protocol. Created by the same designer.
Part1:~ Http$ PROTOCOL_ HTTP is a plain text conversation between a client and a server. The conversation is based on actions performed on resources which are addressed by URL’s.
Part1:~ Http$ URL_ Every resource has an unique URL that consists of several parts.
Part1:~ Http$ VERBS_ The actions that can be performed on a resource are called ‘methods’ or ‘verbs’. Below the most used verbs (there are many more). POST – create PUT – update DELETE – delete GET – read PATCH – partial update TRACE – echo HEAD – headers only
Part1:~ Http$ Request_ Requests and responses contain header-fields and possibly ‘content’. Everything is plain text. Headers usually contain metadata or indicate conversation preferences.
AUTHENTICATION Part1:~ Http$ JSON RESPONSE_
Part1:~ Http$ STATUS CODES_ Every response contains a status code.
PART 2 REST BASICS
Part2:~ Rest$ ENDPOINTS_ The REST protocol is based on ‘endpoints’, which are operations on resources addressed by URL’s. Endpoints can be bundled to form an API.
ACTION RESOURCE <verb> https://<host>/<api_version>[/<resource_type>/<instance_id>] GET https://animal.api/1/lions (returns collection) GET https://animal.api/1/lions/harry@lion.com (returns single lion) POST https://animal.api/1/lions (create new element) PUT https://animal.api/1/lions/harry@lion.com (updates element) PATCH https://animal.api/1/lions/harry@lion.com (partial update) DELETE https://animal.api/1/lions (deletes collection) DELETE https://animal.api/1/lions/harry@lion.com (deletes single element) GET http://www.example.com/1/customers/33245/orders/8769/lineitems/1 GET https://animal.api/1/lions?start=100&count=50 GET https://animal.api/1/lions?id=100&id=103&id=107 (parameter-array) Part2:~ Rest$ ACTION + RESOURCE_ An endpoint has a very strict URL structure. This is key to ‘REST’. Map your functional application resources onto the WWW and allow them to be manipulated.
Part2:~ Rest$ ANTI-PATTERNS_ REST is not SOAP. An URL is NOT a RPC-address or method, it is an universal RESOURCE locator Bad REST API (bad URL’s in general): POST https://domain.com/updateProfile POST https://domain.com/deleteProfile POST https://domain.com/createProfile Good REST API: PUT https://domain.com/1/profiles/piet@puk.com DELETE https://domain.com/1/profiles/piet@puk.com POST https://domain.com/1/profiles GET https://domain.com/1/profiles/piet@puk.com
AUTHENTICATION • HTTP BASIC AUTH Client sends user/password in special header with each API-call. Simple, safe, good choice for API-2-API • TOKEN AUTH Get a temporary access token from API, use in API-calls in username part of HTTP BACIS AUTH, simple, safe, good choice for WEB-2-API • OAUTH2 Industry standard. Flexible. Safe. Part2:~ Rest$ AUTHENTICATION_
Part2:~ Rest$ JAVA EXAMPLE_ HttpResponse<JsonNode> jsonResponse = Unirest .post("http://httpbin.org/post") .header("accept", "application/json") .queryString("apiKey", "123") .field("parameter", "value") .field("foo", "bar") .asJson();
PART 3 API BASICS
Part3:~ Api$ RULE NUMBER ONE_ A REST-server must be client-state agnostic! To be flexible and scalable the server needs to be ignorant of client-state or context. A REST-server does not store session data on behalf of the client. Put another way: all necessary context MUST be in the request. As far as the REST-server is concerned every call is the first call.
Part3:~ Api$ Economy_ There is an API for that. REST-API’s are the glue of the Internet of Things.
Possible clients of your API: • Other API’s • Web applications and web front ends (like AngularJS, ReactJS, JQuery web apps) • Mobile app’s, applications etc. • Machines, bots • Typically NOT humans or ‘end users’ API’s are the glue of the internet of things (IoT). Part3:~ Api$ Users_ On the internet nobody knows you’re a machine.
• Coherent • Cohesive (Only lists purposeful endpoints) • Complete (has all necessary endpoints for its purpose) • Minimal (Only one way to do things) • Encapsulating (hiding implementation details) • Self-explaining • Documented!  Design an API ‘outside-in’, as a product for a generic client. Not just as the library for your specific front-end.  Consider adding the role ‘interface designer’ to the team. Part3:~ Api$ Interface quality_ Good interface design is crafmanship.
• The API • Endpoint documentation • A dashboard to register apps / obtain an API-key • Language stubs (Java, PHP, Python, etc.) on Github • Registration on programmableweb and similar • A homepage / productpage • A revenue-model / pricing • A launchparty • Hackathons Part3:~ Api$ deliverables_ An API is a product, treat it as such.
Some of the choices only you can make: • Few methods / large responses vs. many methods / small responses Considerations: web clients generally like large aggregated responses tailored to their page structures. Other clients like smaller responses. Etc. There is also the underlying (logical) data model and the ‘natural granularity’ of the problem-domain. In most cases: map the data model onto URL’s. • URL parameters vs request headers (for instance the API-tokens) Considerations: in general non-functional data should be in headers. Headers are more easily inspected / used by tools like webservers, giving transport flexibility. • Hypermedia communication (follow-up URL’s in responses, HATEOAS) Problematic concept, very client dependent. Most API’s don’t have this, why should yours? Part3:~ Api$ Interface choices_ Good interface design is crafmanship.
• A REST client, e.g. the Chrome POSTMAN plugin (most IDE’s have one as an add-on) • TELNET (the generic HTTP client) • http://www.restapitutorial.com/resources.html • https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md • http://jsonapi.org/ Part3:~ Api$ RESOURCES_

More Related Content

REST-API introduction for developers

  • 1. Super simple introduction to REST-API’s For programmers By Patrick Savalle, innovation architect Delta Lloyd NV.
  • 5. REST is HTTP/1.1. It is the native protocol of the web. Advantages are: • Every tool that can handle Web / HTTP, can handle REST as native ‘content’. For instance gateways, web-servers and browsers can effectively cache, route, verify, manipulate REST requests or responses. • In short the whole web supports REST • It is simple and elegant • Less diversity in technology, you already use HTTP Part1:~ Http$ WHY REST?_ REST is HTTP. It is the same protocol. Created by the same designer.
  • 6. Part1:~ Http$ PROTOCOL_ HTTP is a plain text conversation between a client and a server. The conversation is based on actions performed on resources which are addressed by URL’s.
  • 7. Part1:~ Http$ URL_ Every resource has an unique URL that consists of several parts.
  • 8. Part1:~ Http$ VERBS_ The actions that can be performed on a resource are called ‘methods’ or ‘verbs’. Below the most used verbs (there are many more). POST – create PUT – update DELETE – delete GET – read PATCH – partial update TRACE – echo HEAD – headers only
  • 9. Part1:~ Http$ Request_ Requests and responses contain header-fields and possibly ‘content’. Everything is plain text. Headers usually contain metadata or indicate conversation preferences.
  • 11. Part1:~ Http$ STATUS CODES_ Every response contains a status code.
  • 13. Part2:~ Rest$ ENDPOINTS_ The REST protocol is based on ‘endpoints’, which are operations on resources addressed by URL’s. Endpoints can be bundled to form an API.
  • 14. ACTION RESOURCE <verb> https://<host>/<api_version>[/<resource_type>/<instance_id>] GET https://animal.api/1/lions (returns collection) GET https://animal.api/1/lions/harry@lion.com (returns single lion) POST https://animal.api/1/lions (create new element) PUT https://animal.api/1/lions/harry@lion.com (updates element) PATCH https://animal.api/1/lions/harry@lion.com (partial update) DELETE https://animal.api/1/lions (deletes collection) DELETE https://animal.api/1/lions/harry@lion.com (deletes single element) GET http://www.example.com/1/customers/33245/orders/8769/lineitems/1 GET https://animal.api/1/lions?start=100&count=50 GET https://animal.api/1/lions?id=100&id=103&id=107 (parameter-array) Part2:~ Rest$ ACTION + RESOURCE_ An endpoint has a very strict URL structure. This is key to ‘REST’. Map your functional application resources onto the WWW and allow them to be manipulated.
  • 15. Part2:~ Rest$ ANTI-PATTERNS_ REST is not SOAP. An URL is NOT a RPC-address or method, it is an universal RESOURCE locator Bad REST API (bad URL’s in general): POST https://domain.com/updateProfile POST https://domain.com/deleteProfile POST https://domain.com/createProfile Good REST API: PUT https://domain.com/1/profiles/piet@puk.com DELETE https://domain.com/1/profiles/piet@puk.com POST https://domain.com/1/profiles GET https://domain.com/1/profiles/piet@puk.com
  • 16. AUTHENTICATION • HTTP BASIC AUTH Client sends user/password in special header with each API-call. Simple, safe, good choice for API-2-API • TOKEN AUTH Get a temporary access token from API, use in API-calls in username part of HTTP BACIS AUTH, simple, safe, good choice for WEB-2-API • OAUTH2 Industry standard. Flexible. Safe. Part2:~ Rest$ AUTHENTICATION_
  • 17. Part2:~ Rest$ JAVA EXAMPLE_ HttpResponse<JsonNode> jsonResponse = Unirest .post("http://httpbin.org/post") .header("accept", "application/json") .queryString("apiKey", "123") .field("parameter", "value") .field("foo", "bar") .asJson();
  • 19. Part3:~ Api$ RULE NUMBER ONE_ A REST-server must be client-state agnostic! To be flexible and scalable the server needs to be ignorant of client-state or context. A REST-server does not store session data on behalf of the client. Put another way: all necessary context MUST be in the request. As far as the REST-server is concerned every call is the first call.
  • 20. Part3:~ Api$ Economy_ There is an API for that. REST-API’s are the glue of the Internet of Things.
  • 21. Possible clients of your API: • Other API’s • Web applications and web front ends (like AngularJS, ReactJS, JQuery web apps) • Mobile app’s, applications etc. • Machines, bots • Typically NOT humans or ‘end users’ API’s are the glue of the internet of things (IoT). Part3:~ Api$ Users_ On the internet nobody knows you’re a machine.
  • 22. • Coherent • Cohesive (Only lists purposeful endpoints) • Complete (has all necessary endpoints for its purpose) • Minimal (Only one way to do things) • Encapsulating (hiding implementation details) • Self-explaining • Documented!  Design an API ‘outside-in’, as a product for a generic client. Not just as the library for your specific front-end.  Consider adding the role ‘interface designer’ to the team. Part3:~ Api$ Interface quality_ Good interface design is crafmanship.
  • 23. • The API • Endpoint documentation • A dashboard to register apps / obtain an API-key • Language stubs (Java, PHP, Python, etc.) on Github • Registration on programmableweb and similar • A homepage / productpage • A revenue-model / pricing • A launchparty • Hackathons Part3:~ Api$ deliverables_ An API is a product, treat it as such.
  • 24. Some of the choices only you can make: • Few methods / large responses vs. many methods / small responses Considerations: web clients generally like large aggregated responses tailored to their page structures. Other clients like smaller responses. Etc. There is also the underlying (logical) data model and the ‘natural granularity’ of the problem-domain. In most cases: map the data model onto URL’s. • URL parameters vs request headers (for instance the API-tokens) Considerations: in general non-functional data should be in headers. Headers are more easily inspected / used by tools like webservers, giving transport flexibility. • Hypermedia communication (follow-up URL’s in responses, HATEOAS) Problematic concept, very client dependent. Most API’s don’t have this, why should yours? Part3:~ Api$ Interface choices_ Good interface design is crafmanship.
  • 25. • A REST client, e.g. the Chrome POSTMAN plugin (most IDE’s have one as an add-on) • TELNET (the generic HTTP client) • http://www.restapitutorial.com/resources.html • https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md • http://jsonapi.org/ Part3:~ Api$ RESOURCES_

Editor's Notes

  1. Voorbeeld van een set REST-API methode. Deze is geprogrammeerd in PHP 7.1 en je ziet de automatisch gegenereerde quick reference op de root van het API-domein.
  2. In the basis HTTP is a text oriented protocol. You can use TELNET to construct and send requests.
  3. Verbs indicate the action on the URL in the request. All verbs: https://www.iana.org/assignments/http-methods/http-methods.xhtml