Level 7 - Milestone 1

Milestone 1 - Introduction to API concepts

The purpose of the first milestone is to provide students with all of the basic knowledge that they need in order to understand what they will be accomplishing in this level

Before completion of this milestone, students will:

  • Download IntelliJ
  • Gain a basic understanding of (RESTful) APIs
  • Decide on a topic for their project
  • Find and verify an API from which to source the data

Downloading IntelliJ IDEA

IntelliJ is an IDE that has a number of features that, combined, make it a very attractive option as an IDE. While switching IDEs may seem daunting, one of the benefits of IntelliJ is the shallow learning curve. As one reviewer noted: "[switching to IntelliJ] made me feel as though I had been dating the wrong person my entire life." This is not to imply that IntelliJ is without any faults, but in the opinion of some, it feels as though it does a much better job of staying out of the way and seamlessly facilitating development. While the instruction to follow are meant to be platform agnostic, and perhaps using Eclipse won't cause any adverse side-effects, this course was developed using IntelliJ, and the possibility exists that there may be some steps left out which Eclipse alone requires. Whatever path you choose, at least ensure that all of your students are using the same setup.

You can have the students download the community edition of IntelliJ, as it is free and indistinguishable from Ultimate edition for the purpose of this class.

Introduction to APIs

A presentation on APIs is provided below. You may want to go through the presentation ahead of time to ensure you are comfortable discussing all of the topics.

Intro to APIs presentation

Introduction to the Level 7 project

Discuss with the students exactly what this project hopes to accomplish:

  • Spring Boot REST API
  • Using another API to retrieve data about a topic
  • A web page that displays the results from their application. Creating this is not within the scope of this class.
  • Verifying our code works with unit testing and integration testing

Finding a topic for the project

Our application is going to use another API to source relevant data for our users. Since students will spend months on this project, it is ideal to find a topic that they are reasonably excited about. You can start with a brainstorming session regarding interests that the students have, and also look up available APIs to get an idea of what is out there. While there may be a temptation to include multiple APIs as sources of data, this should be undertaken with extreme caution. If the application uses more than one API, that will require adding an additional repository class to communicate with it, adding additional data transfer objects for that API, adding additional unit tests for that repository class, as well as adding addition logic to the service layer that homogenizes the results from each API into a single, uniform domain object that we can return to the users.

If appropriate based on timing, you can task the students with continuing to think about what topics may interest them, and then make a final decision the following class.

Finding a source for the data

This section is strongly related the the previous one, as it may turn out that there are no good APIs for the idea that the students came up with. Here are a few questions to keep in mind when selecting an API from which to source the data:

API Quality

  • Does the API follow REST principles?
  • Is this someone's personal project, or developed by a group of professionals?
  • Is this API being continuously maintained?

API Documentation

  • Does the API have a swagger page, or a web page describing the endpoints?

API Usage

  • Does the API provide the information we are looking for?
  • Is the API free to use?
  • Are there any relevant request rate limits?

Finalizing the source of the data

Before making a final decision on what API will be used to retrieve data for this project, make sure that it works as expected. You maybe need to create an account at this point to receive an access token to use with your requests, if the API requires authentication. Use postman, your browser, or the API's swagger page (if it exists) to verify that you can actually make requests and receive an appropriate response.