Blog de Joe Freeman

Be explicit about your service behavior and service return codes.  REST is great but you need to understand the types of failures you can have.  Some may be actual failures.  Others may be successful service invocations with a failure to complete business operations because of business rules. Document the meaning, ownership, and handling behavior of your Service return codes.  Do not assume your partner teams and calling systems have any expectations or understanding beyond success and not-success .  Ask other teams, you  call,  for their Service return code documentation. Force them to document their expectations. Proposed Return Code Category Types Create response categories.  Determine the owner and expected behavior possibilities for each category for services you build.  The following is a basic categorization. HTTP Code Category Remediation Owner Remediation Success Everyone Application or none required Business Error Bu...

Victory has 100 fathers. No-one wants to recognize failure.     The Italian Job Developers and designers spend a fair amount of time creating API, streaming and service contracts.  The primary focus tends to be around happy path API invocation with a lot of discussion about the parameters and the data that is returned.   Teams seem to spend little time on the multitude of failure paths often avoiding any type of failure analysis and planning.  Plan ahead and learn what failure or partial failure looks like and how you will handle it. At the API level: Some groups standardize on  void  methods that throw Exceptions to declare errors. The list of possible exceptions and their causes is not documented.  Exceptions contain messages but no structured machine readable data. At the REST web service level: Some groups standardize on service return values other than 200  for errors. They do not document all of the HTT...