Trattare con API e messaggi di errore

3

Siamo in procinto di costruire un'API (usando WCF).

Finora ho notato 2 modi in cui i metodi potrebbero andare storto a causa di problemi con i parametri inviati.

  1. formato errato, ad esempio abbiamo un parametro data stringa che dovrebbe essere in un determinato formato, se è in un formato diverso il metodo non può continuare.
  2. se un ruolo del metodo è di fare qualcosa identificato da un ID, ma quell'ID non esiste nell'applicazione (DB)

Per prima cosa abbiamo pensato di lanciare un'eccezione, ma ora mi rendo conto che questa non è veramente una situazione "eccezionale", questo tipo di cose è piuttosto comune.

In questo momento ci occupiamo di esso nel modo seguente:

Abbiamo una classe astratta che si chiama APIResponse. ha una variabile di successo booleana e una serie di messaggi per il client dell'API. Ogni gruppo di metodi ha un'implementazione corrispondente di questa classe e questo sarà l'oggetto restituito.

è questo tipo di approccio ok?

    
posta Mithir 21.08.2012 - 12:56
fonte

1 risposta

4

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 .

    
risposta data 21.08.2012 - 13:05
fonte

Leggi altre domande sui tag