Agility, Java programming, New technologies and more…
  • rss
  • Home
  • Management
  • Agile Programming
  • Technology
  • Linux
  • Event
  • Android app
  • Contact
  • About the author
  • English
  • Francais

API, REST, JSON, XML, HTTP, URI… What language do you speak?

Fabian Piau | Monday June 23rd, 2014 - 06:07 PM
  • Print
  • Twitter
  • LinkedIn
  • Facebook
  • Pocket

 Version française disponible

Web services

REST (Representational State Transfer) is a standard used for developing web services. As the name suggests, a web service makes available a service through web technologies. In other words, the calling system asks a service to the called system via the web which in turn provides an answer. The answer can be negative if the system called does not or cannot fulfill the requested service. This principle of architecture allows systems to communicate with each other. The interest is even more evident for heterogeneous systems using different technologies with compatibility issues (through “direct” communication).


A standardized… standard

With REST, communication is based on web technologies and more precisely on HTTP (Hypertext Transfer Protocol) and URI used by the WorldWide Web. Messages are transmitted in a standardized format. For the integration of responses, the format generally used is JSON (JavaScript Object Notation), more lightweight and less verbose than XML (eXtensible Markup Language) but XML can, of course, be used.

The following is the representation (deliberately simplified) of a train trip:

Using JSON:

{
	"trainNum": 123456789,
	"departure": {
		"station": "Bruxelles-Central",
		"time": "07:28"
	},
	"arrival": {
		"station": "Liège-Guillemins",
		"time": "08:25"
	}
}

And the XML equivalent:

<trip>
	<trainNum>123456789</trainNum>
	<departure>
		<station>Brussels-Central</station>
		<time>07:28</time>
	</departure>
	<arrival>
		<station>Liège-Guillemins</station>
		<time>08:25</time>
	</arrival>
</trip>

The data interpretation is very simple as these representation formats are easy to read. Complexity is often related to the data itself. Speaking of traveling in train is not very difficult here.

In today’s technologies, REST web services are very popular for several reasons:

  • An obvious simplicity
  • The use of HTTP whose qualities are demonstrated. The current version of this protocol is 1.1, dated of 1999 (even before IE6). In computing, we can say that it is very old…
  • Systems are increasingly modular, the need for interaction and communication continues to grow.


What about “real life”? Are REST and web services useful?

Yes! Perhaps, you use them every day without paying attention. For example, the fact that you connect to an application using your Facebook account involves some calls to a web service. The third party application asks Facebook whether you authorized it to access your information (email, name, friends list), if so, it provides this information to the application. This exchange allows you to authenticate to the third party application. Such an authentication mechanism/account creation is widely used because:

  • Many people use social networks (Twitter, Facebook, Google+)
  • Users don’t have to create another account (and therefore provide yet another password).

It is even more important to properly secure your social account because if it’s getting hacked, all your associated accounts become vulnerable. On this topic, I encourage you to read this previous article “Some basic rules to prevent your accounts from getting hacked”.


Technically, what’s happening under the hood?

Calling a web service is done via a standard HTTP request and a standard HTTP response is received. The request can be of type GET (to retrieve data in read-only), POST (to submit data for modification purpose), you can read the complete list of HTTP methods/verbs here. The response will depend on the request and its associated data, this may be the famous 404 response to indicate that the content has not been found, a 403 status because you do not have enough privileges, you can find the complete list of status codes here. Of course, you also have the status 200 to indicate that everything went well (OK status), with a potential response in XML/JSON.

There are some best practices to follow when implementing web services. Examples of what not to do:

  • Use a POST request to retrieve data while a GET would have been more appropriate (because the data is not modified)
  • Return an empty value (null) with a status 200 when the data has not been found while status 204 or 404 are precisely designed for this.

Also, it is very important that calls are idempotent, i.e. when the same request is sent several times, the response must be consistent. For instance:

  • I send a POST request to modify data, I receive a status 200 confirming me that the data has been modified
  • If I send the same POST request again, I should now receive a status 304 indicating that the data has not been modified.

Sending the same request several times should never be a problem, you must ensure that the system manages it without side effects.


Let’s talk API

So far we have seen that web services are used to make existing systems communicate with each other, actually there is another main use case. Developers can rely on available web services to develop new features or even build a complete application. In this case, we are talking about API: Application Programming Interface.

To continue with social networks example, let’s take the Twitter API now. Twitter provides a set of REST-based methods to retrieve and manipulate tweets. There are many services available, you can take a look at the complete list of Twitter web services here.

Let’s use a Twitter web service based on a GET. Requests of type GET are easier to test, especially because a click in the browser is enough to create and send the request. The following URL creates a GET to retrieve the list of French tweets concerning this year’s World Cup.

  • https://api.twitter.com/1.1/search/tweets.json?q=worldcup2014&lang=fr

Actually, you’ll figure out that the response is not a list of tweets but some error message. You must also add the authentication parameters (ultimately, the click was not enough). In fact, APIs are usually protected and require to be registered before being used. At least, you get the picture and received a JSON response from Twitter (even if it was an access denied…).

We have talked mainly about the Twitter API, but there are thousands of web services and API available. The Google Maps API allows the developer to integrate custom maps. No doubt this openness was one of the ingredients of such success. Indeed, many applications and websites use the Google mapping data to provide new services. Google has a real business plan for companies.

Finally and if you are curious, you can take a look at ProgrammableWeb, a collaborative website that references many API.

Related posts

people-linkedDoing some social REST with HATEOAS URL, URI, URNThe meaning of URL, URI, URN swaggerSwagger, the automated API documentation devoxxDevoxx UK 2018 – Day 2
Comments
No Comments »
Categories
Agile programming
Tags
api, http, json, rest, uri, url, urn, webservice, xml
Comments rss Comments rss
Page 1 of 11
Download CarmaBlog App

RSS feeds

  • RSS feed RSS - Posts
  • RSS feed RSS - Comments

Most viewed posts

  • Changing the language in Firefox - 115,579 views
  • Using Google Forms / Drive / Docs to create an online survey - 63,166 views
  • FAQ – Online survey with Google Forms / Drive / Docs - 52,403 views
  • Customizing Gnome 3 (Shell) - 30,017 views
  • The meaning of URL, URI, URN - 17,251 views
  • Java EE & CDI vs. Spring - 15,442 views
  • Open Street Map, better map than Google Maps? - 14,648 views
  • Comparing NoSQL: Couchbase & MongoDB - 14,082 views
  • Firefox Nightly, Aurora, Beta, Desktop, Mobile, ESR & Co. - 13,087 views
  • API, REST, JSON, XML, HTTP, URI… What language do you speak? - 12,718 views

Recent Comments

  • Pauline on FAQ – Online survey with Google Forms / Drive / DocsMerci Fabian, mais le but étant que nos clients pu…
  • Fabian Piau on FAQ – Online survey with Google Forms / Drive / DocsProbablement mais ces options sont en général paya…
  • Pauline on FAQ – Online survey with Google Forms / Drive / DocsBonjour Fabian, Merci de votre retour, oui j'avais…
  • Fabian Piau on FAQ – Online survey with Google Forms / Drive / DocsBonjour Pauline, ce n'est pas possible de créer un…
  • Pauline on FAQ – Online survey with Google Forms / Drive / DocsBonjour, Je suis en train de créer un Google Forms…

Recent posts

  • How to write a blog post? At least my way! - 3 months and 2 weeks ago
  • Bot Attacks: You are not alone… - 1 year and 11 months ago
  • Flagger – Monitor your Canary deployments with Grafana - 2 years and 8 months ago
  • Flagger – Canary deployments on Kubernetes - 2 years and 10 months ago
  • Flagger – Get Started with Istio and Kubernetes - 2 years and 10 months ago
  • Expedia CoderDojo in London - 3 years and 7 months ago
  • Volunteering at Devoxx4Kids - 3 years and 10 months ago
  • A Java 11 migration successful story - 4 years and 2 months ago
  • Tips to make your WordPress website secure - 4 years and 5 months ago
  • Devoxx UK 2018 – Day 2 - 4 years and 9 months ago
  • Devoxx UK 2018 – Day 1 - 4 years and 9 months ago
  • Wise, Revolut and Monzo, a small revolution for travelers and expats - 5 years and 1 month ago
  • Autocomplete for Git - 5 years and 10 months ago
  • Swagger, the automated API documentation - 6 years and 2 weeks ago
  • Microservices architecture – Best practices - 6 years and 5 months ago
Buy me a coffee

Language

  • Français
  • English

Follow me!

Follow me on Linkedin
Follow me on Twitter
Follow me on Stackoverflow
Follow me on Github
Follow me on Rss
Link to my Contact

Email subscription

Enter your email address to receive notifications of new posts.

Tags

.net agile agility android bash best practices blog cache cloud computing conference continuous integration css developer devoxx docker eclipse extreme programming firefox flagger google helm hibernate istio java job jug kubernetes london mobile computing overview performance plugin programmer script security sharing society spring tdd test tool ubuntu windows wordpress

Links

  • Blog Ippon Technologies
  • Blog Publicis Sapient
  • Blog Zenika
  • Classpert
  • CommitStrip
  • Coursera
  • Le Touilleur Express
  • Les Cast Codeurs Podcast
  • OCTO talks !
  • The Twelve-Factor App

Categories

  • Event (15)
  • Linux (3)
  • Management (8)
  • Agile programming (29)
  • Technology (45)

Archives

  • December 2022 (1)
  • April 2021 (1)
  • June 2020 (1)
  • May 2020 (2)
  • July 2019 (1)
  • May 2019 (1)
  • December 2018 (1)
  • October 2018 (1)
  • June 2018 (1)
  • May 2018 (1)
  • January 2018 (1)
  • May 2017 (1)
  • March 2017 (1)
  • October 2016 (1)
  • April 2016 (2)
  • March 2016 (1)
  • November 2015 (1)
  • May 2015 (1)
  • February 2015 (1)
  • December 2014 (1)
  • November 2014 (1)
  • September 2014 (2)
  • August 2014 (1)
  • July 2014 (2)
  • June 2014 (1)
  • April 2014 (1)
  • March 2014 (1)
  • February 2014 (2)
  • January 2014 (1)
  • December 2013 (1)
  • November 2013 (1)
  • October 2013 (3)
  • September 2013 (5)
  • July 2013 (1)
  • June 2013 (1)
  • May 2013 (1)
  • April 2013 (1)
  • March 2013 (2)
  • February 2013 (1)
  • January 2013 (2)
  • December 2012 (2)
  • October 2012 (1)
  • September 2012 (1)
  • July 2012 (1)
  • May 2012 (1)
  • April 2012 (1)
  • March 2012 (1)
  • February 2012 (1)
  • January 2012 (2)
  • December 2011 (1)
  • November 2011 (2)
  • October 2011 (2)
  • September 2011 (1)
  • July 2011 (1)
  • June 2011 (2)
  • April 2011 (1)
  • March 2011 (1)
  • February 2011 (1)
  • January 2011 (2)
  • November 2010 (2)
  • September 2010 (1)
  • August 2010 (1)
  • July 2010 (1)
  • June 2010 (1)
  • May 2010 (1)
  • April 2010 (1)
  • March 2010 (1)
  • February 2010 (1)
  • December 2009 (1)
  • November 2009 (1)
  • October 2009 (2)
  • September 2009 (2)
  • August 2009 (3)
  • July 2009 (1)
  • June 2009 (2)
Follow me on Twitter
Follow me on Linkedin
Follow me on Stackoverflow
Follow me on Rss
Link to my Contact
Follow me on Github
 
Fabian Piau | © 2009 - 2023
All Rights Reserved | Top ↑