Home > 2010 Fall DPS907 > Providing an API for your ASP.NET Web Forms app – an introduction

Providing an API for your ASP.NET Web Forms app – an introduction

September 13, 2010 Leave a comment Go to comments

We begin our study here – what is an API for a web app?

.

We know that an application programming interface – API – enables interaction with other software. You have used APIs in many of your Computer Studies program courses; they are present in language libraries, programming frameworks (e.g. .NET and Java), and operating systems.

In general, an API defines the following:

  • The methods which can be called
  • Arguments for a method
  • Return value for a method
  • Allowable data type definitions
  • Calling conventions (e.g. invocation, security, and so on)

An API for a web app is a good thing. It is an easy-to-use, and easy-to-provide, way to access and expose functionality to remote callers. A web app API is easy to use or access, because it uses the standard HTTP protocol to connect to a standard URI.

There are two web app API styles in wide use today: Web Services, and Representational State Transfer. They are introduced below, but feel free to learn more about each by starting with their Wikipedia articles, and then moving on to other learning resources.

.

Web Services

Web Services use XML messages that conform to the Simple Object Access Protocol (SOAP). While there are many "moving parts" to Web Services technologies, it is fairly easy to get started with Web Services in ASP.NET.

From a programmer’s point of view, a Web Service "server" is created as an endpoint in a web app (i.e. it has a URI). Instead of creating a "web form", the programmer creates a "web service". Then, the programmer writes methods for this web service which can be called by remote callers.

In summary, a Web Service "server" is an endpoint that exposes methods to callers.

When a method is called (by a remote caller), a SOAP message is posted to the endpoint. The SOAP message includes the name of the method to be called, and argument data if required. The Web Service "server" returns a SOAP message that includes the status/success result of the call, and typically return value data.

.

Representational State Transfer (REST)

REST can be considered an after-the-fact description of the World Wide Web’s functionality.

From a programmer’s point of view, a REST "server" is an endpoint in a web app. In contrast to a web service, where the methods are determined by the programmer, REST methods are predefined. The methods which can be called are the four HTTP protocol (RFC 2616) methods below:

  • POST – creates a new resource/item/object
  • GET – gets/retrieves an existing resource
  • PUT – updates an existing resource
  • DELETE – deletes an existing resource

The data that passes between the caller/client and the server is in a format that’s defined by the REST "server" programmer.

You should also be aware that this style is typically called "RESTful web services". As a result, both styles are known as, and referred to as, "web services". What words or terminology do we use to distinguish them?

  • SOAP web services (or SOAP XML web services) for the first style
  • RESTful web services for the second style

.

Data payloads

There are two web app API data payload formats in wide use today: XML and JSON.

Web Services use XML, specifically XML messages that conform to (the) SOAP (protocol).

REST typically uses either XML or JSON messages.

.
Both XML and JSON are text-based language-independent data interchange formats.

.

XML – eXtensible Markup Language

In your program of study, you have formally learned about XML beginning in the first Internet programming course. As you learned, and now know, the XHTML markup language is an implementation of XML.

The following is a general and brief review of XML:

XML is a text-based language-independent data interchange format.

It is described in the W3C XML recommendation.

XML includes a set of rules that describes the encoding of documents which can be passed as messages between "clients" and "servers" on the Internet.

The rules are designed to standardize the document’s overall structure, and specify the way that the content can be expressed. However, the rules are not limiting, because they enable the programmer/author to implement their document design (using a schema), within a standardized document framework.

During this course, we will use XML data payloads in some of our examples.

.

JSON – JavaScript Object Notation

JSON is a text-based language-independent data interchange format.

It is described in RFC 4627.

JSON defines a small set of formatting rules for the portable (i.e. serializable) representation of structured data. JSON can represent these types; the first four are primitive types, and the last two are structured types:

  • string
  • number
  • boolean
  • null
  • object
  • array

During this course, we will use JSON data payloads in some of our examples.

.


Advertisements
Categories: 2010 Fall DPS907
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: