web-dev-qa-db-ja.com

推奨されるServiceStack API構造

APIを構築するための最良の方法を試しています。標準のREST構造（1つをリスト、すべてをリスト、作成、更新など）でセットアップしたレビューがあります。例に合わない場合は、各レビューがイベント、場所、または事物など、1つ以上の他のタイプにリンクされます。

私の考えでは、URLは次のようになります：/ event/reviews /（またはこの逆の例：/ reviews/event /）/ location/reviews// thing/reviews /

しかし、私が見ることができる問題は、これらのそれぞれの「GET」が親オブジェクト、つまりイベントを返す必要があることです。

それでは、ServiceStackを使用して、このシナリオを処理する最良の方法は何ですか？すぐに使用できるRESTセットアップを乱用するのではなく、各データリクエストに対してカスタムサービスを作成するのですか、それとももっと基本的なものを見逃したのですか？

c#apiservicestack
66
Tim

まず、「最良の」ソリューションはかなり主観的な用語です。私は一般に、最小限の労力、摩擦、おしゃべりを促進する、DRYの再利用可能な高性能ソリューションを目指しますが、他の人はRESTの原則にどれだけ忠実に「ベスト」を定義するかもしれません。そのため、目標が何であるかに応じて、さまざまな反応が得られます。アプローチ方法のみを提供できます。

ServiceStackサービスの実装は、カスタムルートから分離されています

留意すべきことの1つは、サービスを任意のルートで公開できるため、ServiceStackでサービスを定義および設計する方法は、公開方法がかなり分離されていることです。 ServiceStackはメッセージベースの設計を推奨しているため、各操作に個別のメッセージを与える必要があります。

論理/階層Url構造を使用する

階層的な構造の名詞の識別子を表すことを目的とする論理的なURL構造を使用します。つまり、親パスはリソースを分類し、意味のあるコンテキストを提供します。したがって、この場合、イベントとレビューを公開したい場合は、次のURL構造を使用します。

/events             //all events
/events/1           //event #1
/events/1/reviews   //event #1 reviews

これらの各リソース識別子には、任意のHTTP動詞を適用できます

実装

実装では、通常、メッセージベースの設計に従い、応答タイプと呼び出しコンテキストに基づいて、関連するすべての操作をグループ化します。このために私は次のようなことをします：

[Route("/events", "GET")]
[Route("/events/category/{Category}", "GET")] //*Optional top-level views
public class SearchEvents : IReturn<SearchEventsResponse>
{
   //Optional resultset filters, e.g. ?Category=Tech&Query=servicestack
   public string Category { get; set; } 
   public string Query { get; set; }
}

[Route("/events", "POST")]
public class CreateEvent : IReturn<Event>
{
   public string Name { get; set; }
   public DateTime StartDate { get; set; }
}

[Route("/events/{Id}", "GET")]
[Route("/events/code/{EventCode}", "GET")] //*Optional
public class GetEvent : IReturn<Event>
{
   public int Id { get; set; }
   public string EventCode { get; set; } //Alternative way to fetch an Event
}

[Route("/events/{Id}", "PUT")]
public class UpdateEvent : IReturn<Event>
{
   public int Id { get; set; }
   public string Name { get; set; }
   public DateTime StartDate { get; set; }
}

イベントのレビューでも同様のパターンに従ってください

[Route("/events/{EventId}/reviews", "GET")]
public class GetEventReviews : IReturn<GetEventReviewsResponse>
{
   public int EventId { get; set; }
}

[Route("/events/{EventId}/reviews/{Id}", "GET")]
public class GetEventReview : IReturn<EventReview>
{
   public int EventId { get; set; }
   public int Id { get; set; }
}

[Route("/events/{EventId}/reviews", "POST")]
public class CreateEventReview : IReturn<EventReview>
{
   public int EventId { get; set; }
   public string Comments { get; set; }
}

実装は、これらのメッセージに基づいてかなり単純である必要があります（コードベースのサイズに応じて）2EventsServiceおよびEventReviewsServiceクラス。同じ名前のデータモデルと競合しないように、サービスリクエストのDTO名には複数形を使用しています。

ここではUpdateEventとCreateEventを分離していますが、ユースケースが許せば、それらを単一のべき等StoreEvent操作にマージすることもあります。

物理プロジェクト構造

理想的には、ルートレベルAppHostプロジェクトは軽量で実装不要である必要があります。少数のサービスしか持たない小規模なプロジェクトの場合、すべてを単一のプロジェクトに入れて、必要に応じて必要に応じてアーキテクチャを単純に拡張してもかまいません。

中規模から大規模のプロジェクトでは、この例の目的のために、アプリケーションがEventManと呼ばれると仮定する物理構造を推奨します。

プロジェクトの順序も依存関係を示しています。トップレベルのEventManプロジェクト参照allサブプロジェクト、最後のEventMan.ServiceModelプロジェクト参照none：

- EventMan
    AppHost.cs              // ServiceStack ASP.NET Web or Console Host Project

- EventMan.ServiceInterface // Service implementations (akin to MVC Controllers)
    EventsService.cs
    EventsReviewsService.cs

- EventMan.Logic            //For larger projs: pure C# logic, data models, etc
    IGoogleCalendarGateway  //E.g of a external dependency this project could use

- EventMan.ServiceModel     //Service Request/Response DTOs and DTO types
    Events.cs               //SearchEvents, CreateEvent, GetEvent DTOs 
    EventReviews.cs         //GetEventReviews, CreateEventReview
    Types/
      Event.cs              //Event type
      EventReview.cs        //EventReview type

とともに EventMan.ServiceModel DTOは独自の個別の実装と依存関係のないdllに保存されているため、このdllを任意の.NETクライアントプロジェクトでそのまま共有できます。これは、汎用の C＃サービスクライアント code-genなしでエンドツーエンドの型付きAPIを提供します。

更新

137
mythz

それがあなたのシナリオ/理解に役立つかどうかはわかりませんが、このプレゼンテーションは役に立ちます：

美しいREST + JSON APIの設計

13
MikeT