1

Introduction to RESTful Web ServicesPresented by Steve Ives

2

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

3

What are Web Services?

4

What are Web Services?

• Published APIs• Great alternative to

custom components• Standard protocols and

payloads• Zero client footprint

“Software systems designed to support interoperable machine-to-machine interaction over a network.” (W3C)

• Called by client software• Desktop or server apps• Websites• Other web services• Mobile apps• Internet of Things

• Web services expose• Data• Business logic• Via the web• Remote procedure

calls via standard tools

5

How Are Web Services Implemented?

6

How Are Web Services Implemented?

CODE + NETWORKPROTOCOL

DATAFORMAT+=WEB

SERVICE

Web services are cross-platform language-independent remote function calls.

7

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!

8

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

9

Web Service Data Interchange FormatsSimple Object Access Protocol (SOAP) – 792 charactersPlain XML – 556 charactersJavaScript Object Notation (JSON) – 401 characters

• Most web services now use JSON.• Some continue to offer XML alternative.• Most frameworks serialize & deserialize

data automatically.

10

Why Are Web Services Used?

11

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.

12

Categories of Web Services

13

Public API• Common use cases

• Public information or service• Selling information or service• App store mobile apps• Published desktop apps

• Audience• Open to anyone• Often requires registration• May require fees

• Connectivity• Internet

• API• Usually designed for widespread use

Web service

Application &data servers

Various &unknown

consumers

Internet

14

Restricted Use API• Common use cases

• B2B, interaction with partner entities• Supporting a mobile app

• Audience• Limited, known, authorized

• Connectivity• Internet

• API• Typically designed for a single specific

consumer/appWeb service

Application &data servers

Internet

Customer or vendorapplication server

Companymobile app(external use)

15

Private API• Common use cases

• Corporate web sites• Systems integration• Internal use mobile apps

• Audience• Restricted, internal, controlled

• Connectivity• Internet or private network

• API• Sometimes specific to a single use case• Sometimes general purpose

• Enterprise Service Bus (ESB)Application &data servers

Web service

Internet

Companymobile app(internal use)

In-house remoteapplication

In-house localapplication

Corporateweb server

ESB

16

History of .NET Web Service Technologies

17

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!

18

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

19

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

20

RESTful Web Services

21

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

22

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

23

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

24

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

25

Data Passed via Request/Response BodyGET, POST, and PUT PATCH

26

Completion StatusSuccess status codes• 200 – OK

• Success• Data is present in the response body

• 204 – No content• Success• No data in response• E.g., successful update or delete

• 201 – Created• A POST or PUT operation resulted in a new

entity being created• Location header contains URL

Failure status codes• 400 – Bad request

• Invalid call to service• Bad URL, missing headers, inappropriate

data• Client programming error

• 401 – Unauthorized• Authentication is required and the client is

not authenticated

• 403 – Forbidden• The authenticated user does not have

required permissions

• 404 – Not found• The requested resource does not exist

• 500 – Internal server error• Server programming error

27

Example Request and ResponseRequest sent TO serverPOST /api/orders HTTP/1.1Host: www.acme.comContent-Type: application/jsonContent-Length: 108{“account”:10986223,“ponumber”:19734,“items”:[{“sku”:“ABB701”,“quantity”:1},{“sku”:“CRD100”,“quantity”:10}]}

Response returned FROM serverHTTP/1.1 201 CreatedLocation: www.acme.com/api/orders/14432

Programmers only ever see this in log files…libraries do all the work!

28

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

29

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

30

Taking RESTful Services to the Next Level…OData

31

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!

32

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)

33

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

34

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

35

Example OData Query – Drill into Related Datahttps://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)))

36

Why are RESTful Web Services Important to Your Business?

37

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)

38

Why the Big Focus on RESTful Web Services?

39

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!

40

41

• 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

42

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!)

43

Who has the first question?Introduction to RESTful Web Services