Introduction to RESTful Web Services Presented by Steve Ives 1 Introduction to RESTful Web Services • What are web services? • How are web services implemented? • Why are web services used? • Categories of web services • History of .NET web service technologies • RESTful web services…the “state of the art” • OData services…taking things to the next level • Importance to your business? • Focus during this conference • Teaser…Harmony Core 2 What are Web Services? 3 What are Web Services? “Software systems designed to support interoperable machine-to- machine interaction over a network.” (W3C) • Web services expose • Called by client software • Published APIs • Data • Desktop or server apps • Great alternative to • Business logic • Websites custom components • Via the web • Other web services • Standard protocols and • Remote procedure • Mobile apps payloads calls via standard tools • Internet of Things • Zero client footprint 4 How Are Web Services Implemented? 5 How Are Web Services Implemented? Web services are cross-platform language- independent remote function calls. WEB NETWORK DATA = CODE + + SERVICE PROTOCOL FORMAT 6 Web Service Code • Web services contain operations that perform various actions. • Operations are methods…web services are remotely callable functions. • The clever part is the network messaging, serialization of data, etc. • The easy part is writing the code! 7 Web Service Network Protocols • HTTP or HTTPS • Simple and effective protocol • Widely supported across platforms & development environments • Internet friendly • Firewall friendly • Occasionally other protocols within private LAN • WCF socket endpoints, etc. • Specific one-to-one scenarios 8 Web Service Data Interchange Formats SimplePlainJavaScript XML Object – Object556 Access characters Notation Protocol (JSON) (SOAP) – 401 – 792 characters characters • Most web services now use JSON. • Some continue to offer XML alternative. • Most frameworks serialize & deserialize data automatically. 9 Why Are Web Services Used? 10 Why Are Web Services Used? • Achieve interoperability between systems & applications • Combine best aspects of component-based development & web • Platform & language agnostic • Decoupled • Clients don’t know or care how services are implemented. • Services don’t know or care how clients are implemented. • Follow the rules and it just works! • Scalable (if well designed) • Multiple deployment options • Great ROI • Expose functionality once. • Call it from multiple client apps. 11 Categories of Web Services 12 Public API Various & unknown • Common use cases consumers • Public information or service • Selling information or service • App store mobile apps • Published desktop apps • Audience • Open to anyone • Often requires registration Internet • May require fees • Connectivity Web service • Internet • API • Usually designed for widespread use Application & data servers 13 Customer or vendor Restricted Use API application server • Common use cases • B2B, interaction with partner entities • Supporting a mobile app Company • Audience mobile app (external use) • Limited, known, authorized • Connectivity • Internet Internet • API • Typically designed for a single specific Web service consumer/app Application & data servers 14 In-house remote Private API application • Common use cases • Corporate web sites • Systems integration • Internal use mobile apps Company mobile app (internal use) • Audience • Restricted, internal, controlled Corporate web server • Connectivity Internet • Internet or private network In-house local application • API • Sometimes specific to a single use case Web service ESB • Sometimes general purpose • Enterprise Service Bus (ESB) Application & data servers 15 History of .NET Web Service Technologies 16 ASP.NET Web Services • Introduced in .NET 1.0 (2002) • Look for .asmx • Pretty much died when WCF was introduced (2005)! • Transport • Always HTTP[S] • Data protocol • SOAP (verbose XML dialect) • WSDL • XML file describing the service to custom tooling • Easy to use from environments with WSDL tooling • .NET “add service reference” generates client-side code • Difficult to use from other environments • Producing and parsing complex SOAP messages • Performance and scalability—not great! 17 Windows Communication Foundation • Introduced in .NET Framework 3.0 (Visual Studio 2005) • Last significant update in .NET Framework 4.5 (Visual Studio 2012) • More flexible & capable than ASMX • Multiple network transports • HTTP, TCP, named pipes, etc. • Still SOAP-based, but improved performance • Early REST capabilities “shoehorned in” to later versions • Heavily configuration based • Good and bad • Simple to code, nightmare to configure! • Could be fast, but scalability could be a BIG issue 18 ASP.NET Web API • Introduced in .NET Framework 4.0 (Visual Studio 2010) • Now open source and actively developed • Now supported by .NET Framework and .NET Core • Total focus on RESTful web services • Easy to learn and use • Fully compatible with Synergy .NET • Microsoft finally focused on performance! • Fast and scalable, current “best of breed” • Current “state of the art” for .NET web services 19 RESTful Web Services 20 RESTful Web Services • Representational State Transfer • An architectural style, not a product, transport, or protocol • A set of constraints to be used for creating web services • Access & manipulate textual representations of resources in a uniform and stateless way • Architectural goals • Accessibility from any environment • Simplicity through use of a uniform interface • Performance and scalability • RESTful implementations leverage various standards • URI RFC 3986 • HTTP RFC 7230 - 7237 • JSON RFC 7159 21 Consistent Interface & Standard Operations • URLs identifiy the type of entity being addressed • Standards apply, naming conventions, etc. • These URLs are known as “routes” or “endpoints” • HTTP method used to access URL determines operation type • Create, read, update, delete, etc. • Inbound data passed in two ways • Path parameters (in the URL) • Body data (in the request body) • Outbound data (if any) passed in the HTTP response body • Completion status indicated by the HTTP response status code 22 URLs Identify Entity Being Addressed • https://services.domain.com/api/customers • The collection of customer entities • https://services.domain.com/api/customers/123456 • The specific customer with customer ID 123456 • https://services.domain.com/api/customers/state/CA • The collection of customers in California • https://services.domain.com/api/customers/state/CA/rep/1200 • The collection of customers in California assigned to rep 1200 • Each of these endpoints is mapped to a method in the code 23 HTTP Methods Identify Operation Type • GET /api/customers • Read all customers • GET /api/customers/12345 • Read one customer • POST /api/customers • Create new customer (primary auto assigned by service) • New customer data passed in request body • PUT /api/customers/12345 • Create or update specific customer (all properties) • Customer data passed in request body • PATCH /api/customers/12345 • Partial update specific customer (individual properties) • Change instructions passed in request body • DELETE /api/customers/12345 • Delete specific customer 24 Data Passed via Request/Response Body GET, POST, and PUT PATCH 25 Completion Status Success status codes Failure status codes • 200 – OK • 400 – Bad request • Success • Invalid call to service • Bad URL, missing headers, inappropriate • Data is present in the response body data • Client programming error • 204 – No content • Success • 401 – Unauthorized • No data in response • Authentication is required and the client is • E.g., successful update or delete not authenticated • 403 – Forbidden • 201 – Created • The authenticated user does not have • A POST or PUT operation resulted in a new required permissions entity being created • Location header contains URL • 404 – Not found • The requested resource does not exist • 500 – Internal server error • Server programming error 26 Example Request and Response Request sent TO server POST /api/orders HTTP/1.1 Host: www.acme.com Content-Type: application/json Content-Length: 108 {“account”:10986223,“ponumber”:19734,“items”:[{“sku”:“ABB701”,“quantity”:1},{“sku”:“CRD1 00”,“quantity”:10}]} Response returned FROM server HTTP/1.1 201 Created Location: www.acme.com/api/orders/14432 Programmers only ever see this in log files…libraries do all the work! 27 Advantages of RESTful Web Services • Simple to learn, build, and use • URLs, HTTP, and basic CRUD operations • Simple to write and document • Completely open, reach more clients • Less overhead • Less duplication • More standardized • Testable • Around 70% of public APIs are implemented as RESTful services 28 ASP.NET Web API • Open source framework for building RESTful Web APIs • No SOAP, no WSDL • HTTP transport • Preference for JSON, XML supported • Closely related to ASP.NET MVC • Models and controllers, familiar to many • Convention over configuration • Naming conventions, verbs map to HTTP methods, etc. • Easy to learn, use, and deploy • GREAT performance & scalability • HUGE improvement over earlier technologies 29 Taking RESTful Services to the Next Level…OData 30 OData V4 - Open Data Protocol • “An open protocol that allows the creation & consumption of queryable and interoperable RESTful APIs in a simple and standard way” (Wikipedia) • Initially a Microsoft technology, now open source & independent • Takes RESTful web services to a whole new level • Expose a collection