Intro to REST

REST comes from REpresentational State Transfer. It is a way of encoding state in the url/uri.

• Status codes
  • https://www.mnot.net/blog/2017/05/11/status_codes
  • https://www.restapitutorial.com/httpstatuscodes.html

Notions

• idempotence - https://www.restapitutorial.com/lessons/idempotency.html

Best practices

• api design topics - https://github.com/RestCheatSheet/api-cheat-sheet#api-design-cheat-sheet
• https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• https://softwareengineering.stackexchange.com/a/273359/5218
• ⚠️ http codes should not represent business logic
  • It is wrong to mix HTTP status codes and REST status codes.
  • references
    • server - Should I use HTTP status codes to describe application level events - Software Engineering Stack Exchange

      Very insightful. The strongest argument here is the (impedance) mismatch between HTTP status codes and your app's return values. This can become a nightmare on the long run. Further, I highly support the separation of concerns between the transport (HTTP) and the payload (app data). If you mistype the URL of a service endpoint, you get a 404. If you ask the service for a non-existent item, you get an app-specific message (maybe with additional information you can use to solve the problem). CONS:

      • 1. You must make your request/response logic a subset of the HTTP rules; or
      • 2. You must reuse certain rules, and then the separation of concerns tends to get fuzzy.
      • The other benefit of this approach, which is worth mentioning, is that applications should, generally speaking, not be dependent upon an underlying transport protocol (from a logical point of view).
    • rest - Http Status Code When Downstream Validation Fails - Software Engineering Stack Exchange

      HTTP Status Codes are only designed to tell you about the status of your HTTP transmissions. They have no notion of "business rules." Stick to 200 and 400. When you get a 400, you can retry the request or fail it. When you get a 200, your message is valid; you can then check the returned metadata for status information from your application (i.e. whether the payment succeeded or not).

    • http code rest vs business - Google Search
    • rest - Should HTTP status codes be used to represent business logic errors on a server? - Software Engineering Stack Exchange
    • rest - Why would HTTP response code be used in RESTful service to indicate business related logic? - Stack Overflow
    • REST – Why HTTP Status Codes Are Important | FileCatalyst
    • REST HTTP codes for business logic errors - Stack Overflow
    • rest - Http status for error response because of business exception. Syntax is correct and request makes sense - Stack Overflow
    • http - Which status code should I use for failed validations or invalid duplicates? - Stack Overflow
    • Designing a REST API: setting business logic error codes in http headers or within the response payload - Software Engineering Stack Exchange
    • What http error to return in case of validation and business rules in a domain driven design api - Software Engineering Stack Exchange
    • rest architecture style - https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

    • I use HTTP 200 everywhere because Facebook says it's the best practice now #graphql

Tools

• vscode plugin
  • https://marketplace.visualstudio.com/items?itemName=humao.rest-client
    • simple http files similar to get/post requests but also with variables
    • http files are sources shared with the team in the project
• swagger
• JSON path evaluator online
  • http://jsonpath.com/

Not recommended

• postman - https://www.getpostman.com/
  • vendor lock-in, proprietary format, needs cloud account, forces team to make accounts, in the end you must pay for simple things
• SoapUI - old style, desktop app

API discovery

• SoapUI
  • https://www.soapui.org/rest-testing-discovery/rest-discovery---api-with-internal-browser.html
• Swagger?
• hateoas - https://restfulapi.net/hateoas/

Resources

• • See more about API and ABI here: https://stackoverflow.com/questions/2171177/what-is-an-application-binary-interface-abi/2497903#2497903