Classroom Discussion - REST APIs, JSON & DTOs

• What is a URI? What is a URL?
• What information does a URI give us?
• Looking at https://api.example.com/users/42, what might users and 42 represent?
• What is the difference between identifying a resource and performing an action on it?
• Why might /users/42 be preferable to /getUser?id=42 in a REST-style API?

• What is JSON?
• Why is JSON so commonly used for communication between systems?
• What types of values can JSON contain?
• How would you represent a person with:
  • A name?
  • An age?
  • An address?
  • A list of hobbies?
• What happens if the JSON returned by an API changes?

• What is a data structure?
• What is the difference between a simple value and a complex data structure?
• When would we use:
  • A List?
  • A Set?
  • An array?
  • A Map?
  • An object?
• How can nested JSON be represented using Java classes?
• If a Person has an Address, should Address be its own class? Why or why not?

• What is a DTO?
• What does DTO stand for?
• Why don’t we just work directly with the JSON string?
• What advantages does a UserDTO give us compared with manually extracting values from JSON?
• Should a DTO contain business logic, or should it primarily represent data?
• How closely should our DTO match the API’s JSON structure?

• How would you represent the following JSON as a Java DTO?

  {
    "name": "Anna",
    "age": 25
  }
  

• What could happen if the JSON contains first_name but the Java property is called firstName?

• What happens if the JSON contains fields that our DTO doesn’t have?

• What happens if our DTO expects a field that isn’t returned by the API?

• What is serialization?

• What is deserialization?

• Why might we want to convert a DTO back into JSON?

• What is a REST API?
• What makes an API “RESTful”?
• What is a resource?
• What is the difference between /users and /users/42?
• What are the purposes of:
  • GET?
  • POST?
  • PUT?
  • PATCH?
  • DELETE?
• Can the same URI be used with different HTTP methods?
• What would be the difference between GET /users/42 and DELETE /users/42?

• What is an HTTP status code?
• What does 200 mean?
• What does 201 mean?
• What does 400 mean?
• What does 401 mean?
• What does 403 mean?
• What does 404 mean?
• What does 500 mean?
• Does receiving an HTTP response necessarily mean that the request was successful?
• Why should we check the status code before processing the response body?

• What happens when our Java application calls an API?
• What does the application send to the API?
• What does the API send back?
• Where is the JSON located in an HTTP response?
• What information do we need before we can request data from an API?

• What can go wrong when our application calls an API?
• What happens if the URI is incorrect?
• What happens if the server is unavailable?
• What happens if the resource doesn’t exist?
• What happens if authentication fails?
• What happens if the server returns a 500 error?
• What happens if the returned JSON is invalid?
• What happens if the JSON structure doesn’t match our DTO?
• What is the difference between an HTTP/network problem and a JSON conversion problem?

• What is the HttpClient class?
• What is HttpClient responsible for?
• What isn’t HttpClient responsible for?
• What is an HttpRequest?
• What is an HttpResponse?
• How do we perform a GET request using HttpClient?
• How can we access the response body?
• How can we access the HTTP status code?
• Does HttpClient automatically convert JSON into a Java object?
• Why should we check the HTTP status code before converting the response body?

• What is Jackson?
• Why would we use Jackson instead of manually parsing JSON strings?
• What can Jackson convert?
• What does Jackson need to know to convert JSON into a Java object?
• What problems might arise with:
  • Different field names?
  • Missing values?
  • Additional values?
  • Dates?
  • Nested objects?
  • Arrays?

• What is the ObjectMapper class?

• What library does ObjectMapper belong to?

• What happens when we call:

  objectMapper.readValue(json, UserDTO.class);
  

• How does Jackson know which JSON properties belong to which Java fields?

• What does readValue() do?

• What does writeValueAsString() do?

• When might we convert a DTO into JSON?

• What is a complex data structure?
• How do we represent nested JSON using DTOs?
• If an order contains a customer, should the customer have its own DTO?
• If an order contains multiple items, what Java data structure could we use?
• When should we create multiple DTO classes instead of one large DTO?
• How many DTO classes would you create for an order containing:
  • Order information?
  • Customer information?
  • A delivery address?
  • A list of order items?
• Why is it useful to understand the JSON structure before designing our DTOs?

• What happens between pressing Run and seeing API data printed by our Java application?
• What is the role of the URI?
• What is the role of HttpClient?
• What is the role of the REST API?
• What is the role of the HTTP response?
• What is the role of JSON?
• What is the role of Jackson?
• What is the role of ObjectMapper?
• What is the role of the DTO?
• Where should HTTP errors be handled?
• Where does JSON-to-Java conversion happen?

• Can you explain this entire flow in your own words?

  URI
   ↓
  HttpClient
   ↓
  HTTP Request
   ↓
  REST API
   ↓
  HTTP Response
   ↓
  JSON
   ↓
  Jackson / ObjectMapper
   ↓
  DTO
   ↓
  Java Application
  

• If the application fails, at which points in this flow could the problem have occurred?

• How would you determine which part of the flow caused the problem?