Mi piace questo approccio, è totalmente accettabile.
Dai un'occhiata all'API di Flickr. Stanno usando anche i codici di errore e i messaggi di errore nella loro risposta api.
link
link
(metodo API di esempio)
Fornire codici di errore e messaggi di errore invece di eccezioni è molto meglio quando si tratta di più framework client (sconosciuti) (.net, java, ecc.) Se un'implementazione di API client è errata perché sta usando un formato sbagliato , è molto meglio visualizzare il messaggio di errore dal server ("Formato data non valido. Deve essere ggMMyyy.") invece di ottenere uno strano "FormatException" (+ stacktrace).
Avere id di errore e messaggi di errore:
- migliora l'usabilità di api
- migliora la manutenibilità
- migliora l'esperienza utente / sviluppatore
L'utente API (sviluppatore) potrebbe fare facilmente riferimento al suo problema e risparmiare tempo. sarebbe molto più facile rintracciare un possibile bug / attività con uno errorId / errorMessage specifico anziché avendo "Hey, sto ricevendo quelle strane eccezioni quando chiami XYZ. Cosa sto facendo di sbagliato?"
Modifica in base alla richiesta:
Diciamo che abbiamo una "BaseResponse" (simile alla tua risposta APIR, i commenti sono spogliati per una migliore leggibilità)
public class BaseResponse
{
public int ErrorId { get; set; }
public string ErrorMessage { get; set; }
public bool Successful { get; set; }
}
E stiamo avendo una GetDocumentResponse (implementata da DocumentService, vedi sotto)
public sealed class GetDocumentsResponse : BaseResponse
{
public IList<Document> Documents { get; set; }
}
Contratto di DocumentService
[ServiceContract]
public interface IDocumentService
{
[OperationContract]
[WebInvoke(
Method = "POST",
BodyStyle = WebMessageBodyStyle.WrappedRequest,
ResponseFormat = WebMessageFormat.Json,
RequestFormat = WebMessageFormat.Json)]
GetDocumentsResponse GetDocuments(string date);
}
Implementazione di DocumentService (semplificato)
public GetDocumentsResponse GetDocuments(string date)
{
bool isFormatValid = // parse Date
if (!isFormatValid)
{
// Response = static class, provides generic responses and sets properties of response
return Response.ProvideFault<GetDocumentsResponse>(100, "The date-format is not valid. Valid: mmddyyyy");
// return new GetDocumentsResponse { Successful = false, ErrorId: 100, ErrorMessage = "The date-format is not valid. Valid: mmddyyyy"};
}
var documents = this.documentRepository.GetDocuments(...)
return new GetDocumentsResponse { Successful = true, Documents = documents };
}
Quindi, diciamo che sono uno sviluppatore e voglio usare questa API.
1. - Effettuare una chiamata API valida e amp; ottenere una risposta valida dal server
(Risposta JSON)
{
"ErrorId":0,
"ErrorMessage":null,
"Successful":true,
"Documents":[
{
"DocumentId":13,
"Name":"xyz"
}
]
}
2. - Effettuare una chiamata API non valida & ottenere una risposta non valida dal server
{
"ErrorId":100,
"ErrorMessage":"The date-format is invalid. Valid: mmddyyyy",
"Successful":false,
"Documents":[
]
}
Quindi, per la prima chiamata ho fatto tutto bene.
La seconda chiamata dice chiaramente che cosa è sbagliato, non devo cercare alcune eccezioni specifiche di .NET (o meglio: errori wcf) se sono uno sviluppatore java. In pochi secondi dopo aver ricevuto la risposta so cosa è andato storto e perché è andato storto . Non devo ricercare documentazione o molto peggio per chiederti dell'attuale implementazione di GetDocuments e perché il mio formato di data non è valido. Salva te e me un sacco di tempo .