Flesh out REST mini-lecture

[neight-allen]

Outline incoming. I'll add it as a comment soon. I think I'd like to teach this some time next week. This should be 30-60 minutes worth of content.

[neight-allen]

REST

• Why do you care?
  • If you're designing an API, REST is a pattern you can use to help you make decisions. Although, you are likely not going to be designing API's for a while.
  • I'm mostly telling you this so that people can't "well actually" you, and you have the option to "well actually" someone else if you want to.
• What is it?
  • Routes are model based
  • Use HTTP verbs
  • Stateless. Every route will behave the same way every time, regardless of what you've done in the past. Only the data will change.
  • Some Examples
• What is not REST?
  • Other (older) API's used SOAP, which I won't go deeply into, but it was defined by commands, like method names, over resources
  • Some Examples
• Why are we using this term in Rails
  • REST and CRUD are related. The REST standard gives you
• Advantages
  • It's a standard. This makes you consistent with other REST services out there, but also consistent across your API. Once someone knows how to CRUD one of your resources, they know how to CRUD the rest
• Where it breaks down
  • I still don't know how to represent a search RESTfuly. Search is not really a resource. You don't edit or update or destroy a search.
  • How would you represent Rails Engine's Business Logic endpoints?

[martensonbj]

Here's the gist for the draft im working on
https://gist.github.com/martensonbj/da6bf07b28919c63bd14145074fa0db5

[neight-allen]

Updated outline

• Why do you care?
  • If you're designing an API, REST is a pattern you can use to help you make decisions. Although, you are likely not going to be designing API's for a while.
  • The trigger for this lesson was from students saying they wanted their Rails Engine projects to be RESTful. REST describes the API interface, and has no opinions about your Rails code. The interface in Rails Engine is pre-defined. You have no control over the RESTfulness of your project.
  • I'm mostly telling you this so that people can't "well actually" you, and you have the option to "well actually" someone else if you want to. And enough to google questions about REST
• What is it?
  • Routes are model based
  • Use HTTP verbs
    • GET
    • POST
    • PUT
    • PATCH
    • DELETE
  • Uniform Interface
    • Resource Based
    • Hypermedia
  • Stateless. The server doesn't remember anything about routes you've hit in the past. Everything to handle the request is contained within the request itself.
  • Some Examples
    • GET /users
    • GET /users/:id
    • DELETE /users/:id
    • GET /repos/:owner/:repo/stats/contributors
    • POST /user/repos
    • GET /merchants?name=planet+express
• What is not REST?
  • REST is not a Rails thing, but Rails does it's best to adopt REST
  • REST says nothing about authentication
  • It's mostly about APIs, although you can make your web routes RESTful if you think that's best
  • Other (older) API's used SOAP, which I won't go deeply into, but it was defined by commands, like method names, over resources
  • Some Examples
    • GET /users/:id/make_admin
    • GET /users/add_filter
    • GET /api/v1/merchants/:id/customers_with_pending_invoices
• What does this all have to do with Rails
  • REST and CRUD are related. resources in a routes file creates RESTful routes for you. Nested resources are also RESTful
  • Controller actions are not RESTful. REST describes the interface. The default controller actions are convention, but you could build a RESTful API without using any of them.
• Advantages
  • It's a standard. This makes you consistent with other REST services out there, but also consistent across your API. Once someone knows how to CRUD one of your resources, they know how to CRUD the rest
• Where it breaks down
  • How do you search for multiple resources? REST would say you don't. Is that practical? Should API's include search functionality? Do you return a 404 if no results are returned?
  • How would you represent Rails Engine's Business Logic endpoints?
• Wrap up
  • Use HTTP verbs when they make sense instead of creating a new route
  • Don't be religious about REST, but know when something is not RESTful, and question whether it could or should be. There may not be any API out there that is 100% RESTful

[martensonbj]

I feel like this somehow either was done or you no longer need it because of the slide deck. Let me know if that is incorrect.