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 of entities • https://apis.myorg.com/api/customers • Query that data in any way you want (examples follow) • One OData endpoint may do hundreds of things • Without coding individual functionality!

31 OData Query Mechanisms • $select=field[,field,…] • Specify the properties returned (like a sparse select)

• $filter=expression • Filter the records that are returned

• $top=n and $skip=n • Page result sets

• $count • Return only the number of matching entities

• Return individual properties (JSON or raw data)

• Drill into related entities (multiple levels)

32 OData Query – Filter Rows and Select Columns https://localhost:8086/odata/Customers?$filter=State eq 'NV'&$select=CustomerNumber,Name

33 OData Query – Filter Rows and Select Columns https://localhost:8086/odata/Customers?$filter=State eq ‘CA’ and CreditLimit gt 5000 &$select=CustomerNumber, Name

34 Example OData Query – Drill into Related Data https://localhost:8086/odata/Customers(8)?$select=CustomerNumber,Name& $expand=REL_Orders($select=OrderNumber,DateOrdered; $expand=REL_OrderItems($select=ItemOrdered,QuantityOrdered,UnitPrice; $expand=REL_ItemOrdered($select=CommonName,Size)))

35 Why are RESTful Web Services Important to Your Business?

36 Why are RESTful Web Services Important to Your Business? • Stand-alone “app islands” rarely satisfy an organizations needs • Diverse best-of-breed apps on multiple platforms • RWS APIs are THE standard way of integrating apps

• Most organizations use apps on multiple platforms • Legacy apps, desktop apps, web apps, mobile apps, etc. • APIs are the “digital glue” that join platforms together • RWS are as open as it gets…anything can talk HTTPS and JSON

• Web & mobile apps are REALLY important to most organizations • RWS are THE standard way of exposing APIs

• Performance & scalability are REALLY important • RWS are inherently fast & scalable (assuming devs don’t screw up!)

• Software development is expensive • RWS are simple, quick & easy to implement & call • And OData takes things to a whole new level! (more later) 37 Why the Big Focus on RESTful Web Services?

38 Why the Big Focus on RESTful Web Services? • Enhancing UX is hugely important to many of you

• Fewer Synergy developers build UI using Synergy tools • WinForms, WPF, UWP, Web Forms, MVC, HTML5, Xamarin Forms, etc. • Often choose an alternate language for UI development

• The SERVER is the application, clients are just platform-specific views

• While “TUI” and “Toolkit” UI is no longer popular… • Huge investment in your code base • Tightly coupled to your SDMS/RMS data

• High demand for exposing logic & data to new UI • APIs are the future, web services are the best way expose APIs • We have some new tools help you!

39 40 • Framework for developing RESTful web APIs that expose Synergy data and business logic • Binary code (NuGet packages) • CodeGen templates • Open source, including all dependencies • Standards-based, building on • ASP.NET Core Web API • OData Core • EF Core • Core Identity • Highly efficient development • Supplied libraries perform the heavy lifting • Extensive use of code generation to implement feature-rich data services • Fill in the gaps with hand-crafted code • Fast and scalable

41 Sessions To Pay Special Attention To… • Demystifying .NET Standard and .NET Core • Setting the technology stage (Steve Ives, Wednesday, 9am)

• Introducing the Harmony Core Open Source Project • So what’s it all about? (Jeff Greene, Wednesday, 10.45am)

• Leveraging EF Core to Access Synergy Data • What’s happening under the hood? (Jeff Greene, Wednesday, 1.30pm)

• Building RESTful Web Services with Harmony Core • How can I do this in my environment? (Steve Ives, Wednesday, 4pm)

• Post-Conference Workshop • Use it all…hands on! (Steve Ives, Friday, 9am until we finish, no later than 3pm!)

42 Introduction to RESTful Web Services Who has the first question?

43