APIs

An application-programming interface (API) is a set of programming instructions and standards for accessing a Web-based application. A software company releases its API to the public so that other software developers can design products that are powered by its service.

For example, Amazon.com released its API so that websites developers could access Amazon's product information more easily. Using the Amazon API, a third party website can post direct links to Amazon products with updated prices and an option to "buy now."

An API is a software-to-software interface, not a user interface. With APIs, applications talk to each other without any user knowledge or intervention. When you buy movie tickets online and enter your credit card information, the movie ticket website uses an API to send your credit card information to a remote application that verifies whether your information is correct. Once payment is confirmed, the remote application sends a response back to the movie ticket website saying it's OK to issue the tickets.

Actually, we have already worked with APIs from The Random User Generator and Giphy to get data with jQuery. In this module we're going to use Zapier, is an automation tool that makes it really easy to connect different services (such as Gmail, Slack, Mailchimp and more) using their APIs, with a simple interface.

Whether it is web services like weather, finances, Facebook, Instagram, Twitter… or our phones, connected devices, and cars, there is an API for that.

First, create an account on Zapier, and follow this 5 minutes tutorial to understand how Zapier works and get a grasp of what we can do with it:

Now that we have a good idea of what Zapier can do, let's get back to the context of this course: Zapier also provides a Webhook services that let us integrate other services on Zapier with our own projects via a simple HTTP request.

To use Webhooks, we're going to create a New Zap using the following steps:

1. Create a new Zap by click on Make a Zap
2. Search and select "Webhooks"
3. Click on the "Catch Raw Hook" button
4. Copy the link (we'll use it later) and then "Continue"
5. Click on "Test Trigger"
6. You shall receive a "Request" with the content that you posted earlier
7. Connect the raw hook to "Google Sheets"
8. Click on "Create Spreadsheet Row".
9. Connect your "Google Account".
10. Connect your "Spreadsheet" and "Worksheet".
11. If your test is successful, click on "Turn on Zap".
12. You should now see the data recorded in your "Google Sheet".

👆👆👆 Click on the steps to view a screen capture of what you should see on your screen

We will use jQuery's $.post() method to post the JSON data on a Zapier Webhooks that is going to trigger an event which will record the data in a Google Sheet. You will be able to retrieve user's data from a webpage and record automatically every input to a Google Sheet.

Replace the value of url by the url you noted in step 4 👆.
You can also find it again by going back to the steps of your Zap 😉

See jQuery.post() documentation for more information on this method.

We've seen in Web Architecture that, with NodeJS and express, we can create a server to respond with HTML and files to requests. Instead of .send() or .sendFile() methods, our server can return JSON with the .json() method:

Our minimal API returns JSON data that we could require with $.getJSON() pointing at https://hello-express-api.glitch.me/.
We could also have several routes to access different services/datasets or event use Express Route Parameters to pass different arguments to our API.

Quiz

Test your knowledge

APIs Project

Assignment

Objectives

You should now have a better understanding of what APIs are and how they are integrated in web services. We are now ready to take a step back from all these new technical concepts in order to grasp how they can add value to various projects, increase their efficiency or improve their impact. You'll conduct and document an exploratory research on existing web projects (if possible partially based on APIs) answering to your Sustainable Development Goal subject (cf the chapter Introduction).

You should make a difference between what your subject is and what the associated SD Goal is. Here you have to focus on your subject as stated in the page Introduction, which is more specific than the general SD Goal.

The pedagogical objectives of this assignment are the following: The pedagogical objectives of this documentation project are the following:

• Gather information:
• on your SD Goal and more specifically on your subject
• on the way APIs are actually integrated in web projects
• Identify
• actual needs on your subject
• potential users and/or beneficiaries of that type of projects
• Practice
• formulating relevant research questions
• creating a user persona
• producing a user scenario
• Project yourself
• in the opportunities brought by web technologies, in particular APIs, to a project of general interest
• in a dynamic of social innovation

This assignment is also the only way to get well prepared for your group project, so be sure to get involved now to make the most of the four weeks of collective prototyping that will follow! Indeed, this research process corresponds to a phase of empathy and inspiration, which is an essential step for generating new ideas.

Instructions

This assignment is mandatory. If you update your work but the link doesn't change, you don't need to re-submit it.

On Glitch, make sure you're always connected when you make your assignment!
Assignments done without being connected are graded 0!

Your assignment will take the form of a web page created and hosted through glitch, just as in the previous part. It should summarize the results of your exploratory research and reflect your understanding of the technologies and of your subject's issues. Your documentation project will take the form of a web page created and hosted through glitch, just as in the previous part. It should summarize the results of your exploratory research and reflect your understanding of the technologies and of your subject's issues.

At first, you'll look for existing projects addressing your subject in an interesting way. They must be digital projects, ideally based on web technologies or on a mobile app. If they use APIs in a way or another, it's even better! You'll probably use mainly a search engine to discover and document such projects, but feel free to use other ways to gather information: specialised magazines, tech or social entrepreneurship events, organizations, incubators... You'll then have to summarize briefly four projects that seem relevant to you, following the detailed structure given below.

Don't forget to write down all your sources during your research!

Then in a second time you will focus on only one of these projects. The choice is up to you, but be sure to explain us why you chose this project among the others. You will deepen both the user experience aspects and the technical principle.

This assignment is evaluated on the quality of your thinking and of your documentation, not on your ability to code or recreate such projects using APIs/Zapier. But if you feel like experimenting more API tools, try to simulate one of the projects, you could earn bonus points!

Structure of your assignment

Be sure to follow strictly the structure given below. Your layout must be very clear and highlight the information hierarchy. Keep in mind that the ability to properly structure and style your page with HTML/CSS will be evaluated!

Your assignment has to be structured as it follows:

Your documentation project has to be structured as it follows:

Presentation

• Subject
The subject assigned to you on the page 'Introduction'
• Technological module
API / Database / AI, which one did you choose?

A. Exploratory research

1. Name of the project n°1

Insert an image to illustrate the project.
1. Project carriers

   The persons, companies, organizations, institutions who carry the project

2. Beneficiaries

   Who benefit from this project? In some projects, the entity can be non-human, such as a certain type of animal species etc.

3. Users

   Who is using this project? There can be several types of users. Also, users may be the same persons as beneficiaries, but not necessarily.

4. Need

   The need the project is answering to

5. Principle

   How is the project answering to the need? What solution is it offering?

6. Main technologies involved

   A list of the main technologies that make the project work.

7. Sources

   Link to the resources you used, the website of the project etc.

8. Other info

   Optional

2. Name of the project n°2

Proceed as for project n°1

3. Name of the project n°3

Proceed as for project n°1

4. Name of the project n°4

Proceed as for project n°1

B. Deepening

1. Name of the selected project

Insert one or several images to illustrate this project.
1. Carriers and actors of the project

   In addition to the persons who carry the project, other actors can contribute to it.

2. Research question

   Take the time to formulate the research question the project is answering to. See in 'Methodological tools' below what is expected from a good research question.

3. The reason you selected this project

2. User scenario

1. Users

   A reminder of who the users are

2. Persona

   Create a relevant persona that could use this project and describe that persona. See tips in 'Methodological tools' below.

3. Key features

   Every action that your user can do with a product is called a feature. The most important features are called key features: list them by order of importance in the form VERB + NOUN (ex: "order food")

4. UX storyboard

   Insert an image of your UX storyboard. It can be a picture if you draw it by hand, or a screenshot / image if you created it on a computer. See tips in 'Methodological tools' below.

3. Technical analysis

1. General principle

   One to two phrases to explain briefly how the project technically works

2. Technical overview - API version

   Write down a detailed technical overview of the project in an "API version", that is:

   • If no APIs are involved in the existing project you're currently documenting, you'll have to imagine how APIs could be integrated in the project for it to have a greater impact / efficiency. Then describe precisely how it would work.
   • If APIs are involved in the existing project you're documenting, then the "API version" is the same as the existing one.
   See what is expected from the detailed technical overview in 'Methodological tÉools' below.

3. Added value thanks to APIs

   In two to three sentences, summarize how APIs improve the project (whether you're working on a fictionnal 'API-version' or on the existing one that already involves APIs)

4. Simulation

If you feel like experimenting more API tools, you can try to simulate the project, for example with Zapier. This part is optional (bonus points). Screenshots, source code, link to your projects... All efforts appreciated!

---

Complementary sources

• Source 1
• Source 2
• Source 3

Methodological tools

This section gives you detailed methodological tips and clarifies what is expected from your documentation on the points Research question, Persona, UX storyboard and Technical overview. Be sure to read it carefully!

Research question

As the name suggests, a research question (sometimes called problematique) is particularly central in a research project, such as a thesis or even a dissertation. But it is more generally a fundamental starting point when you're trying to tackle an issue through a well-defined problem. If you want to propose a relevant solution, which meets a need or a demand, you absolutely must take your time to carefully formulate your research question.

So basically, what is a research question? It is the question that the project sets out to answer. Remember that you have to be the most precise as possible. Your research question must meet all the criterias below:

• it expresses the specific problem the project aims to solve
• it mentions the potential users and ideally the end-beneficiaries
• it gives the context the project focuses on
• it is formulated in an interrogative form

You may not need right now to invent original solutions, but you will have to be innovative in the Part 3 of this course, so take this opportunity to practice formulating a good research question now.

Here are some examples of bad research questions:

• ❌ How can we reduce noise pollution?
  → This is much much too general.
• ❌ How to reduce noise pollution in big cities?
  → Still too general, no context and no users / beneficiaries mentioned.
• ❌ How does the Ambi-city open source mobile app use noise pollution data collected by citizens to educate to this major health issue?
  → This describes the project more than the issue and the context.
• ❌ How can we reduce noise pollution in schools?
  → We're starting to get somewhere, but we're still not sure who the users of the project are and the issue is a bit vague.
• ❌ People raising kids under 8 years old in big cities should have a priority access to the flats that are less exposed to noise pollution.
  → This is a statement, not a question.

Here are some better examples of what can be expected as research questions. As you can see, they are all addressing noise pollution but in quite different ways:

• ✅ How can we motivate city residents to collect noise pollution data with their phones in order to contribute to academic research?
• ✅ How can the municipalities use noise pollution data to orient their urban planning policy?
• ✅ How can we provide reliable noise pollution maps to vulnerable people (e.g. people with chronic high sleep disturbance, cardiovascular problems, etc.) at key moments such as renting a flat or accepting a job offer?
• ✅ How can noise pollution time data improve the daily life of people suffering from anxiety in urban areas?

Now it's your turn to try to formulate a relevant and precise research question regarding the project you're documenting!

Persona

A persona in user-centered design and marketing is a fictional character created to represent a user type that might use a site, brand, or product in a similar way.

W. Lidwell; K. Holden; J. Butler, Universal Principles of Design

Personas are useful in considering the goals, desires, and limitations of users in order to help to guide decisions about a product such as choices of features, interactions, visual design...

Ok so how are we supposed to define such a fictional character? First we must be sure that we're talking about the right type of persons: our concerns here are the actual users of the product, who are not necessarily the same people as the end-beneficiaries. Also, we'll focus on only one type of users.

Then we have to build a profile of the type of users we focus on, by defining a set of characteristics such as their name, motivations, family status, age, etc. What are their habits? Their hobbies or activities? Do they have a job, study? What are their goals, their limitations? Here is a small list of what should be mentioned in your persona's description:

• First name
• Age
• Activity / Profession
• Place of residence, country, environment (city, countryside, etc.)
• Family status
• Income
• List of hobbies and passions
• List of needs, desires, dreams
• List of problems and frustrations
• Major issue related to the subject

You can present all this info the way you want as long as you defined at least all the above characteristics. Fell free to add pictures if it makes your persona more tangible!

UX storyboard

When you'll design a product or service in a user-oriented approach, you'll have to take in account the user experience (UX) you want to offer. Before diving into subtle ergonomic details, we first need to describe the user journey's big picture. A very common and effective tool to do so is the UX storyboard. A storyboard is a sequence of drawings describing a scene. In our case, we'll use storyboards to illustrate how the user interacts with the product. Here are some tips to help you draw a relevant UX storyboard:

First step
Write down the user scenario on a draft, in 5 to 6 steps rather general, with words and not drawings. It is the base of your process, don't include it to your assignment. It must start with the initial situation and end with the resolved situation, and should contain:

• The context of the interaction
• The user's motivations
• The actions performed with the product
• The consequences of the interaction

If your scenario is too long, try to combine some steps or simplify your user flow.

Second step
Transform your scenario in a storyboard by illustrating each step with pens and paper: you'll then have 5 to 6 boxes, the first one illustrating the initial situation and the last one the resolved situation. These drawings will help you show the environment of the user, the key aspects of their interaction with the product, and the evolution of the situation. If you think that your drawings are not clear enough, you can add a short caption under each box to describe the situation. Here are some tips for drawing your storyboard:

• Don't draw wireframes (i.e. the details of the interface), but only the element essential to understand the main interaction (like a single button)
• You can use text in your drawings, for example when your characters talk or think, or to give info about the environment ("in the subway", "at the office" etc.)
• In general, don't draw too much details. Use thick felt-tip pens to avoid multiplying details.
• The artistic esthetic of your drawings is not important at all, but if you really don't feel comfortable with pens and paper you can go with digital illustration.

It's the result of that step, that is the illustrated storyboard, that you will have to include in your assignment (picture of your storyboard or screenshots / .png export of your digital illustrations)

Technical overview - API version

In this part, you'll write down a detailed technical overview of the project in an "API version", that is:

• If no APIs are involved in the existing project you're currently documenting, you'll have to imagine how APIs could be integrated in the project for it to have a greater impact / efficiency. Then describe precisely how it would work.
• If APIs are involved in the existing project you're documenting, then the "API version" is the same as the existing one.

To give a good and detailed technical overview of the project, you must at least answer the following questions:

• Which services' API(s) is (are) used? What other projects use these API?
• Document the general purpose of these APIs and the main opportunities they offer: what kind of data can be accessed? Does the API offer the possibility to filter / sort the datas?
• Which events trigger an API call? How are they set up? Filtered (examples: only if there is the hashtag #something)?
• What kind of information is retrieved in your project?
• How is it used in your project? Is it directly displayed to the user? Or after some modifications? Or never displayed?

You should give as much (relevant) technical details as possible. Don't hesitate to include links of external resources. And remember to always cite your sources!

---

Evaluation criteria

It's time to start your exploratory research! The evaluation criteria are the following:

Participation: 4 points
Time spent on course + interaction with resources / examples

Exploratory research: 4 points
Quality of your exploratory research on the four projects

Selected project deepening: 5 points
Choice of the project and research question, definition of users, persona, key features and UX storyboard

Technical analysis: 4 points
Technical overview - API version, added value thanks to API

HTML & CSS quality: 3 points
Page's structure, use of skeleton, custom CSS, code clarity

Simulation: bonus points
Simulation of the project with Zapier