ASP.NET Web API Podstawy prostego API i co na to wujek WCF

Web ApiCzęść NR.1Web API jest to aplikacja, która może być manipulowana przy użyciu protokołu HTTP. Protokół HTTP zawiera 4 metody (GET,POST,PUT,DELETE) i przy pomocy tych metod manipulujemy Web API. Protokół HTTP nie jest związany szczególnie z żadną platformą. Web API jest wykorzystywane przez wiele urządzeń z różnych platform.

Koncepcja usług HTTP jako źródła danych jest definiowana poprzez adres URL. Sam adres więc stanowi formę zapytania do aplikacji. Metody HTTP stanowią pewny mechanizm wysłania żądania do tej aplikacji.

Powiedzmy, że mamy Web Api i wysyłamy do niego następujące zapytanie poprzez następujący adres URL/

http://usługa/panniebieski/gry/1234

Na podstawie tego adresu możesz się domyślić, że z repozytorium gier pytam o grę o id 1234.

Akcja oczywiście musi się wykonać przez metodę HTTP. Wszystkie informacje o zapytaniu są zawarte w URL i raczej nie są to po ufne dane więc w tym wypadku zostanie użyta metoda GET.

Jeżeli zapytanie do źródła danych byłoby bardzo złożone (n.p chcielibyśmy grę z danego okresu w czasie) wtedy użylibyśmy metody POST.  Skoro parametry zapytania są przechowywane w wewnątrz metody POST w takim razie adres możemy skrócić http://usługa/panniebieski/gry/. Metoda POST też jest bardziej bezpieczna, gdy przesyłamy do usługi poufne dane. Użycie protokół HTTPS jest wtedy także zalecane, ponieważ zapytania POST też można odczytać.

Do zaktualizowania gry po tym adresem URL http://usługa/panniebieski/gry/1234 mogłaby zostać użyta metoda PUT. Do kasowania użylibyśmy metody DELETE.

W zapytania POST i PUT w wewnątrz wywołania przesyłamy parametry definiujące, o jaką grę nam chodzi. Parametry te są reprezentowane w formacie tekstowym. Zazwyczaj jest to XML lub JSON.  W odpowiedzi usługa zwraca informację w podobnym stylu.

Czyli usługa po zapytaniu GET na adres http://usługa/panniebieski/gry/1234 zwróci tekstową reprezentację obiektu "Gry" w formacie JSON lub XML.

Usługi HTTP odpowiadają także odpowiednimi statusami określający sukces lub błąd. Przykładowo, jeśli nie ma  gry o id 1234  powinien zostać zwrócony status 404 – Not Found. Jeżeli wszystko przebiegło prawidłowo powinien zostać  zwrócony status 200 – OK.

ASP.NET Web API

Framework ASP.NET Web API pozwala na utworzenie takiej usługi HTTP i jest on oficjalnie częścią ASP.NET. Do działania potrzebna jest tylko klasa dziedzicząca po „ApiController”.

Powiedzmy, że twoja klasa dziedzicząca po „ApiController”  i ma metodę „GetGame(int id)”.

Framework ASP.NET Web API zmapuje tą metodą na wywołanie GET, do którego trzeba przesłać parametr id w adresie URL.

Wewnątrz metody piszesz kod, który wyciąga tę grę i na końcu po prostu zwracasz obiekt „Gry”.

Framework ten w odpowiedzi do klienta serializuję  ten obiekt do XML lub JSON. Oczywiście działanie frameworka można dostosować do własnych potrzeb.

W przypadku przesłania złożonego parametru  do metody w akcji HTTP typu POST. Framework będzie deserializować format XML lub JSON do obiektu języka C# określonego w parametrze metody.

Wraz z Visual Studio 2012 (mam już 2013) ASP.NET zaoferował nam nowy template związany z budową ASP.NET Web API.

ASP.NET Web API czy WCF Rest, czy JSONResult, czy WebMethod

W .NET oczywiście istniały inne sposoby na zbudowanie HTTP-owego web API. Osobiście wiele razy w pracy zbudowałem aplikacje Web API bazujące na frameworku WCF.

Pytanie więc brzmi, po co sobie zawracać głowę „ASP.NET Web API”.

Gdyż na pierwszy rzut oka oba frameworki robią to samo.

ASP.NET Web API został zbudowany z myślą o wywołaniach tylko przy pomocy protokołu HTTP. WCF został zbudowany głównie z myślą o SOAP – a REST-owy model pojawił się jako drugi w kolejce.

Model programowania ASP.NET Web API przypomina ASP.NET MVC.  Jest on prosty. Zamiast tworzenia interfejsów jak WCF tworzymy klasy, które są udekorowane atrybutami.  ASP.NET Web API jednak nie powstał, aby zastąpić WCF. Jest on bardziej alternatywą dla programistów, którzy znają model MVC i nie chcą się bawić w model WCF, który przez swoje SOAP-owe korzenie jest niepotrzebnie bardziej złożony.

Teraz co ze współpracą ASP.NET z WCF. WCF jest od jakiegoś czasu, a ASP.NET Web API jest nowym dzieckiem z bloku Microsoftu.  Obie technologię jednak są brane pod uwagę, jeśli chodzi o budowę REST-owego API.

WCF wygrywa, jeśli chodzi o elastyczności. Jeśli byś musiał zamienić swoją usługę HTTP na usługę, która używa TCP lub innego protokołu transportującego…no cóż z WCF nie miałbyś z tym dużego problemu, a z ASP.NET Web API stanąłbyś w kropce. WCF także wspiera pewne standardy usług sieciowych jak plik WSDL.

Oczywiście, jeśli chodzi o klientów nie wszyscy wspierają rozwiązanie SOAP. Przykładowo dla telefonów jest ono za ciężkie, nawet jeśli byś na siłę go chciał użyć.

Zrozummy więc podstawowe różnice w programistycznym modelu WCF i ASP.NET Web API.

W WCF interfejsie określamy metodę wywołania GET, jak i ścieżkę.

[ServiceContract]
public interface IGameService
{
    [OperationContract]
    [WebGet(UriTemplate = "/Games/{id}")]
    Game GetGame(string id);
}
public class GameService : IGameService
{
    public Game GetGame(string id)
    {
        return new Employee() { Id = id, Name = "Mortal Kombat" };
    }
}

Klasa musi być oznaczona atrybutami w celu serializacji.

[DataContract]
public class Game
{
    [DataMember]
    public int Id { get; set; }
    [DataMember]
    public string Name { get; set; }
}

Sposób ASP.NET Web API wygląda tak:

public class GameController : ApiController
{
    public Game GetGame(string id)
    {
        return new Game() { Id = id, Name = "Mortal Kombat" };
    }
}

Web API działa tak samo jak kontroler MVC. Wyjątkiem jest fakt, że klasa bazowa tego kontrolera jest „ApiController”. Oznacza to, że WEB API jest przygotowane na testy jednostkowe. WCF w tym trochę kuleje.

Jak bardzo Web API różni się od MVC?

W MVC możesz w końcu stworzyć kontroler z metodą, który będzie zwracać „JsonResult”. Mam nawet wpis o tej funkcjonalności.

Z akcją kontrolera „JsonResult” do adresu URL  jest dodawana nazwa metody HTTP(http://usluga.panniebieski/gry/get/1234)  tworząc w ten sposób model bardziej przypominający wywołanie usługi niż model REST .

Czynności są podkreślane w adresie niż metodach HTTP (GET,POST,PUT,DELETE).

Z ASP.NET Web API ma oczywiście więcej funkcjonalności MVC. (Language negotiation)

MVC wspiera JSONResult tylko ze względu na perspektywę użycia wywołań AJAX na stronie i nie można go porównać z ASP.NET Web API.

WebMethod z klasycznego ASP.NET też wypada z tej kolejki. Przykład użycia tutaj. Użyłem go tylko raz, ponieważ potrzebowałem czegoś na zapełnienie wywołania AJAX na stronie aspx, a nie chciałem budować usługi WCF REST dla jednej metody.

ASP.NET Web API nadaje się do następujących scenariuszy.

• Rich-client web applications: Dla aplikacji które ciągle korzystają ciągle z wywołań AJAX do uzupełnienia swoich danych. Może to być aplikacja napisana w Silverlight,Flash czy w HTML 5.
• Single-page application (SPA) zbudowane na bibliotekach JQuery,Knockout też będą bardzo szczęśliwe z ASP.NET Web API. Zapomnij o JSONResult.
• Aplikacje na telefony: Telefony nie lubią SOAP-u. Model REST jest bardziej przyjazny i najbardziej Cross-platformowym.

ASP.NET Web API został więc stworzony jako uzupełnienie frameworka ASP.NET. Patrząc na  rozwiązania SPA z różnymi frameworkami JavaScript wydaje się oczywiste, dlaczego ten framework powstał.  Nie chcemy odrywać się od projektu WEB i tworzyć WCF tylko pozostać nadal w ASP.NET-cie.

W następnym wpisie utworzymy prostą aplikację Web API.