Kiedy użyć czego? ====== * REST * GraphQL * gRPC --- # Cel W prezentacji prześlędze użycie REST, GraphQl, gRPC w realnych projektach. Przeanalizuje ich mocne strony słabe strony, aby zaznaczyć kiedy dana opcje jest trafnym wyborem. --- # Zawartość * REST * Przykładowa użycia * gRPC * Przykładowa użycia * GraphQL * Przykładowa użycia * Porównanie przypadków użycia * Wnioski --- # REST * Zaproponowany przez Roya T. Fieldinga w 2000 roku. * Standaryzacja metod HTTP i adresów zasobów * Hypermedia * Swobodne budowanie żadań i odpowiedzi. Często wspierane jest kilka formatów danych: XML, JSON. * Zgodny z założenia protokołu HTTP m.in. w kwestii cache --- # Przykład - HyperOne ``https://api.hyperone.com/docs`` ---  --- # gRPC Stworzony przez Google https://opensource.googleblog.com/2015/02/introducing-grpc-new-open-source-http2.html ---  --- Nowe podejście do starego standardu RPC. Wykonywane są konkretne polecenia na zdalnym serwerze, ale do transmisji wykorzystywany jest protokuł biarny. Serializacja odbywa się za pomocą biblioteki protobuff. Kluczową różnicą między gRPC a REST jest sposób, w jaki RPC określa negocjacje umowy. Podczas gdy REST definiuje swoje interakcje za pomocą słów kluczowych w swoich żądaniach, RPC działa na podstawie koncepcji kontraktów, w których negocjacja jest zdefiniowana i ograniczona przez relację klient-serwer, a nie przez samą architekturę. REST jest często postrzegany jako nadmiernie wymagający zasobów, podczas gdy RPC może być używany nawet w sytuacjach ekstremalnie małej mocy. --- # Przykład https://cloud.google.com/vision/docs/reference/rpc/?hl=pl ---  ---  --- ```proto service ImageAnnotator { // Run image detection and annotation for a batch of images. rpc BatchAnnotateImages(BatchAnnotateImagesRequest) returns (BatchAnnotateImagesResponse) { option (google.api.http) = { post: "/v1/images:annotate" body: "*" }; } // Request for performing Google Cloud Vision API tasks over a user-provided // image, with user-requested features, and with context information. message AnnotateImageRequest { // The image to be processed. Image image = 1; // Requested features. repeated Feature features = 2; // Additional context that may accompany the image. ImageContext image_context = 3; } // Response to an image annotation request. message AnnotateImageResponse { // If present, face detection has completed successfully. repeated FaceAnnotation face_annotations = 1; // If present, landmark detection has completed successfully. repeated EntityAnnotation landmark_annotations = 2; // If present, logo detection has completed successfully. repeated EntityAnnotation logo_annotations = 3; // If present, label detection has completed successfully. repeated EntityAnnotation label_annotations = 4; // If present, localized object detection has completed successfully. // This will be sorted descending by confidence score. repeated LocalizedObjectAnnotation localized_object_annotations = 22; // If present, text (OCR) detection has completed successfully. repeated EntityAnnotation text_annotations = 5; // If present, text (OCR) detection or document (OCR) text detection has // completed successfully. // This annotation provides the structural hierarchy for the OCR detected // text. TextAnnotation full_text_annotation = 12; // If present, safe-search annotation has completed successfully. SafeSearchAnnotation safe_search_annotation = 6; // If present, image properties were extracted successfully. ImageProperties image_properties_annotation = 8; // If present, crop hints have completed successfully. CropHintsAnnotation crop_hints_annotation = 11; // If present, web detection has completed successfully. WebDetection web_detection = 13; // If present, product search has completed successfully. ProductSearchResults product_search_results = 14; // If set, represents the error message for the operation. // Note that filled-in image annotations are guaranteed to be // correct, even when `error` is set. google.rpc.Status error = 9; // If present, contextual information is needed to understand where this image // comes from. ImageAnnotationContext context = 21; } // Multiple image annotation requests are batched into a single service call. message BatchAnnotateImagesRequest { // Individual image annotation requests for this batch. repeated AnnotateImageRequest requests = 1; } // Response to a batch image annotation request. message BatchAnnotateImagesResponse { // Individual responses to image annotation requests within the batch. repeated AnnotateImageResponse responses = 1; } // External image source (Google Cloud Storage or web URL image location). message ImageSource { // **Use `image_uri` instead.** // // The Google Cloud Storage URI of the form // `gs://bucket_name/object_name`. Object versioning is not supported. See // [Google Cloud Storage Request // URIs](https://cloud.google.com/storage/docs/reference-uris) for more info. string gcs_image_uri = 1; // The URI of the source image. Can be either: // // 1. A Google Cloud Storage URI of the form // `gs://bucket_name/object_name`. Object versioning is not supported. See // [Google Cloud Storage Request // URIs](https://cloud.google.com/storage/docs/reference-uris) for more // info. // // 2. A publicly-accessible image HTTP/HTTPS URL. When fetching images from // HTTP/HTTPS URLs, Google cannot guarantee that the request will be // completed. Your request may fail if the specified host denies the // request (e.g. due to request throttling or DOS prevention), or if Google // throttles requests to the site for abuse prevention. You should not // depend on externally-hosted images for production applications. // // When both `gcs_image_uri` and `image_uri` are specified, `image_uri` takes // precedence. string image_uri = 2; } ``` --- # GraphQL Podejście GraphQL do idei API klient-serwer jest wyjątkowe wśród tych opcji, ponieważ odwraca standardową relacje. Korzystając z GraphQL, klient określa, jakie dane chcą, w jaki sposób chcą je dostać i w jakim formacie. Jest to odwrócenie klasycznego dyktowania z serwera na klienta i pozwala na wiele rozszerzonych funkcji. GraphQL jest bardzo różny od REST i gRPC w tej kwestii. --- Należy zauważyć, że ogromną zaletą GraphQL jest fakt, że domyślnie zazwyczaj zapewnia najmniejsze możliwe żądanie. Z drugiej strony, REST domyślnie wysyła wszystko, co ma wszystko na raz - najbardziej kompletne żądanie. Z tego powodu GraphQL może być bardziej przydatny w szczególnych przypadkach, w których wymagany typ danych jest dobrze zdefiniowany, a preferowany jest pakiet o niskich danych. --- ```ql= query listRepos($queryString: String!){ search(query:$queryString, type:REPOSITORY, first:20){ repositoryCount pageInfo{ endCursor startCursor } edges{ node{ ... on Repository{ id url defaultBranchRef{ target{ ... on Commit{ history(first:10){ totalCount edges{ node{ ... on Commit{ committedDate } } } } } } } } } } } } ``` --- https://developer.github.com/v4/explorer/ ---  --- ```graphql input MessageInput { content: String author: String } type Message { id: ID! content: String author: String } type Query { getMessage(id: ID!): Message } type Mutation { createMessage(input: MessageInput): Message updateMessage(id: ID!, input: MessageInput): Message } ``` --- # Porównanie przypadków użycia Jak widać, żadna z tych opcji nie jest „lepsza” niż inne, ale pasuje do unikalnych scenariuszy interakcji. --- REST: Bezstanowa architektura do przesyłania danych zależna od hipermedii. REST może połączyć wiele różnych zasobów, które mogą być wymagane w różnych formatach dla różnych celów. REST jest zasadniczo związany z zarządzaniem zasobami bezstanowymi, dlatego najlepiej jest go używać w takich sytuacjach. Systemy wymagające szybkiej iteracji i zgodne z słownictwem HTTP lepiej pasują do tych przypadku. --- gRPC: zwinny i lekki system żądania danych. Z drugiej strony, gRPC najlepiej jest stosować, gdy system wymaga określonej ilości danych lub przetwarzania rutynowo, w których wnioskodawca ma małą moc lub zasoby. IoT jest tego doskonałym przykładem. --- GraphQL: podejście, w którym użytkownik definiuje oczekiwane dane i format tych danych. GraphQL pochodzi z Facebooka i ten rodowód dobrze ilustruje przypadek użycia - sytuacje, w których żądający potrzebuje danych w określonym formacie do określonego zastosowania. W takich przypadkach te formaty danych i relacje między nimi są niezwykle ważne, a żadne inne rozwiązanie nie zapewnia danych odpowiedniej jakości. --- # Podsumowanie Wybór podejścia projektowego jest prawdopodobnie najważniejszą decyzją podjętą we wczesnym rozwoju API. Kazde podejście do tworzenia API wpływa na interakcję użytkownika końcowego z zasobami samego API. Innymi słowy, nie jest to wybór podejścia dla dewelopera - jest to wybór sposobu, w jaki zamierzasz nawiązać relacje z konsumentami.