Jak nie budować API – na przykładzie SPClaimProvider

Miałem ostatnio okazję implementować własny provider claimów do SharePointa. Jak prawie całe API SharePointa, ta kupa kupy woła o pomstę do nieba. Postanowiłem wykorzystać okazję i zaprezentować jak to złe API mogłoby wyglądać, gdyby ktoś w teamie odpowiedzialnym za “dev-experience” tego kolosa miał trochę oleju w głowie.

Ale najpierw kilka słów wprowadzenia, czyli przedstawienie problemu. Dla szczęśliwców nieobeznanych z SharePointem małe screenshoty:

Na powyższym obrazku widzimy ekran do edycji “roli”. Nie musi to być rola w rozumieniu “role-based security”, tutaj nie ma to znaczenia. Znaczenie ma jedynie pole “Role Members” – ten kawałek UI odpowiedzialny jest za skojarzenie listy użytkowników z jakimś elementem (tym elementem jest tutaj rola właśnie). W pole można wpisać cokolwiek, a po kliknięciu ikonki “ludzika z checkboxem” następuje proces “name resolution” – jeśli wpisany tekst da się powiązać z użytkownikiem istniejącym w systemie, to zostanie on podkreślony i będzie traktowany jako jedna całość. W przeciwnym wypadku zobaczymy komunikat o błędzie mówiący, że nie można “zresolwować tekstu i wywnioskować z niego o jakiego usera chodzi”.

Zamiast wklepywać ręcznie nazwę użytkownika możemy posłużyć się dodatkowym mechanizmem – wyszukiwarką. Otwiera się ona po kliknięciu książeczki i wygląda tak:

Ekran podzielony jest na trzy obszary: pole wyszukiwania, drzewko oraz listę wyników wyszukiwania.

Dość o UI.

Własna implementacja claims providera może być odpowiedzialna za cztery rzeczy:

• nadawanie dodatkowych claimów użytkownikom logującym się do systemu (tego nie widać we wklejonym UI)
• “name resolution” – pierwszy screen
• budowanie hierarchii – drzewko na drugim screenie
• wyszukiwanie – lista wyników na drugim screenie

Jakby tego było mało, możemy sobie wybrać co obsługujemy, więc jedna implementacja providera może dorzucać claimy a całkiem inna odpowiadać za wyszukiwanie obiektów.

Czy ma to sens? “Sharepoint developers” powiedzą, że tak. Ale oni pewnie rzadko poza SP wyglądają.

A cała reszta prawdopodobnie za głowę się złapie i zgodnie wskaże jaką zasadę (niejedną zresztą) brutalnie tutaj złamano.

Efektem takiej decyzji jest to, że abstrakcyjna klasa, z której dziedziczę, ma pierdylion metod abstrakcyjnych. Jeśli nie chcę aby mój provider wspierał któryś scenariusz to zostawiam je puste.

Ale skąd SharePoint będzie wiedział które funkcjonalności wspiera moja implementacja? Ano nawet przedszkolak by potrafił takie coś zaprojektować, przecież wystarczy dodać cztery właściwości bool:

• SupportsEntityInformation
• SupportsHierarchy
• SupportsResolve
• SupportsSearch

Fuck yeah!!! Mało tego – SharePoint i tak wywołuje metody, które powyższymi flagami oznaczam jako niewspierane. Żal.pl.

Czytałem sobie o tym na MSDNie, obejrzałem wideło na Pluralsight i… zero komentarza na ten temat. Po prostu przyjęte jest za pewnik, że tak powinno być. I koniec. Nikt nie powie, że to nie ma sensu, ponieważ te funkcjonalności mają ze sobą tyle wspólnego co romantyczna randka i psy walące się na ulicy w pierwszy dzień wiosny. Po prostu poszczególne części klasy dziedziczącej są pozwijane w odpowiednio nazwane regiony i jazda! “MS tak chciał”.

Niewiele na to da się poradzić. Ja starałem się zachować choć trochę porządku w kodzie i (jak pisałem w poście o regionach) rozbiłem implementację na 5 plików partial:

Nie jest idealnie, ale… trochę lepiej.

Ale jak to można było zaprojektować inaczej? Tu również odpowiedź jest prosta. Zamiast narzucać obowiązek implementowania niepotrzebnych metod i sterowania “możliwościami” providera za pomocą durnych flag wystarczyło rozbić funkcjonalności pomiędzy cztery interfejsy. IClaimsAugmentation, IHierarchyProvider, INameResolver, IClaimsEntitySearch… czy jakkolwiek inaczej je tam nazwać można. Nie jedna wielka klasa abstrakcyjna, która robi wszystko. Każdy z tych interfejsów i tak wymaga całkowicie odrębnych metod i wrzucenie ich do jednego wora nie mieści się po prostu w głowie. Przed SharePointem stałoby wówczas banalne zadanie: rzutuj mój provider na interfejs numer jeden. Nie null? Wywołuj metody. Potem rzutuj na interfejs numer dwa… I tak po kolei. Albo po prostu SP mógłby przeszukać assemblies w poszukiwaniu implementacji interfejsów…

Czasami ciężko jest mi zrozumieć skąd takie wynalazki się w ogóle biorą. I to głównie właśnie w produktach z Redmond. Sharepoint, Forefront Identity Manager, Gutek pewnie potwierdzi że podobnie jest w CRM… A niby tam biorą tylko najlepszych.