Más contenido relacionado


Restful api

  1. Restful API Anurag Srivastava
  2. What is REST REST is the underlying architectural principle of the web. The amazing thing about the web is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. The REST architectural style describes six constraints. Uniform Interface Stateless Cacheable Client-Server Layered System
  3. Uniform Interface The uniform interface constraint defines the interface between clients and servers. It simplifies and decouples the architecture, which enables each part to evolve independently. The main guiding principles of the uniform interface are: Resource-Based Individual resources are identified in requests using URIs as resource identifiers. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server does not send its database, but rather, some HTML, XML or JSON that represents some database records expressed.
  4. Uniform Interface Manipulation of Resources Through Representations When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so. Hypermedia as the Engine of Application State (HATEOAS) Clients deliver state via body contents, query-string parameters, request headers and the requested URI (the resource name). Services deliver state to clients via body content, response codes, and response headers. This is technically referred-to as hypermedia (or hyperlinks within hypertext).
  5. Hypermedia as the Engine of Application State (HATEOAS) lHATEOAS stands for Hypertext As The Engine Of Application State. It means that hypertext should be used to find your way through the API. An example: GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <balance currency="usd">100.00</balance> <link rel="deposit" href="/account/12345/deposit" /> <link rel="withdraw" href="/account/12345/withdraw" /> <link rel="transfer" href="/account/12345/transfer" /> <link rel="close" href="/account/12345/close" /> </account>
  6. Stateless As REST is an acronym for REpresentational State Transfer, statelessness is key. Essentially, what this means is that the necessary state to handle the request is contained within the request itself, whether as part of the URI, query-string parameters, body, or headers. The URI uniquely identifies the resource and the body contains the state (or state change) of that resource. Then after the server does it's processing, the appropriate state, or the piece(s) of state that matter, are communicated back to the client via headers, status and response body. So what's the difference between state and a resource? State, or application state, is that which the server cares about to fulfill a request—data necessary for the current session or request. A resource, or resource state, is the data that defines the resource representation— the data stored in the database, for instance. Consider application state to be data that could vary by client, and per request. Resource state, on the other hand, is constant across every client who requests it.
  7. Stateless
  8. Cacheable As on the World Wide Web, clients can cache responses. Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing state or inappropriate data in response to further requests. Well- managed caching partially or completely eliminates some client–server interactions, further improving scalability and performance.
  9. Cacheable
  10. Client-Server The uniform interface separates clients from servers. This separation of concerns means that, for example, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not concerned with the user interface or user state, so that servers can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface is not altered.
  11. Client-Server
  12. Layered System A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load-balancing and by providing shared caches. Layers may also enforce security policies.
  13. API Building an API is one of the most important things you can do to increase the value of your service. By having an API, your service / core application has the potential to become a platform from which other services grow. Facebook, Twitter, Google, GitHub, Amazon The easier your API is to consume, the more people that will consume it.
  14. API
  15. RESTful API Design Definitions Resource: A single instance of an object. For example, an animal. Collection: A collection of homogeneous objects. For example, animals. HTTP: A protocol for communicating over a network. Consumer: A client computer application capable of making HTTP requests. Third Party Developer: A developer who wishes to consume your data. Server: An HTTP server/application accessible from a Consumer over a network. Endpoint: An API URL on a Server which represents either a Resource or an entire Collection. URL Segment: A slash-separated piece of information in the URL.
  16. Authentication An app can use one of two forms of authentication - Basic Auth and Session Auth. All credentials used to access any of the REST APIs can be used with either style of authentication.
  17. Basic Authentication Basic Auth - authenticates each individual request using a username and password pair. The Basic Auth token is reversible, however when all communication is over HTTPS the security context is completely protected. Basic Auth is trivial to use from HTTP client libraries. Tools such as cURL provide corresponding command line options. To use Basic Auth, an app must send an HTTP Authorization header containing the username and password with every request. A Basic Auth authorization string is composed of the word Basic followed by a base64- encoded string containing the username and password separated by a colon. Simple example: Auth string (before encoding in base64): Basic myUsername:myPassword Auth string (after base64 encoding): Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk Complete authorization header: Authorization: Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk
  18. Session Authentication Session Auth - authenticates each individual request using a auth token.By using Session Auth, an app eliminates exposure of passwords on every individual request. Only the initial request for setting up the session needs to be sent with the username and password. To use Session Auth, an app must first make a login request to collect an auth token from the backend. The auth token is returned in the JSON returned in the response. This auth token can then be used for authentication in subsequent requests across all REST APIs. The auth token is cryptographically secured and cannot be reversed. Hence, it’s impervious to forgery. The auth token is cleared from a device when a user is logged out.
  19. Token based authentication The general concept behind a token-based authentication system is simple. Allow users to enter their username and password in order to obtain a token which allows them to fetch a specific resource - without using their username and password. Once their token has been obtained, the user can offer the token - which offers access to a specific resource for a time period - to the remote site.
  20. Token based authentication It will use the following flow of control: The user provides a username and password in the login form and clicks Log In. After a request is made, validate the user on the backend by querying in the database. If the request is valid, create a token by using the user information fetched from the database, and then return that information in the response header so that we can store the token browser in local storage. Provide token information in every request header for accessing restricted endpoints in the application. If the token fetched from the request header information is valid, let the user access the specified end point, and respond with JSON or XML.
  21. Token based authentication
  22. JWTJSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA. Let's explain some concepts of this definition further. Compact: Because of its smaller size, JWTs can be sent through an URL, POST parameter, or inside an HTTP header. Additionally, the smaller size means transmission is fast. Self-contained: The payload contains all the required information about the user, avoiding the need to query the database more than once.
  23. JWT JWT stands for JSON Web Token and is a token format used in authorization headers. This token helps you to design communication between two systems in a secure way. Let's rephrase JWT as the "bearer token" for the purposes of this tutorial. A bearer token consists of three parts: header, payload, and signature. The header is the part of the token that keeps the token type and encryption method, which is also encrypted with base-64. The payload includes the information. You can put any kind of data like user info, product info and so on, all of which is stored with base-64 encryption. The signature consists of combinations of the header, payload, and secret key. The secret key must be kept securely on the server-side. You can see the JWT schema and an example token below;
  24. JWT A JWT would look like the following: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0MTY5MjkxMDksImp0aSI6ImFhN2Y4ZDBhOTVjIiwic2NvcGVzIjpbInJlcG8iLCJwdWJsaWNfcmVwbyJ dfQ.XCEwpBGvOLma4TCoh36FU7XhUbcskygS81HE1uHLf0E
  25. JWTif ($credentialsAreValid) { $tokenId = base64_encode(mcrypt_create_iv(32)); $issuedAt = time(); $notBefore = $issuedAt + 10; //Adding 10 seconds $expire = $notBefore + 60; // Adding 60 seconds $serverName = $config->get('serverName'); // Retrieve the server name from config file /* * Create the token as an array */ $data = [ 'iat' => $issuedAt, // Issued at: time when the token was generated 'jti' => $tokenId, // Json Token Id: an unique identifier for the token 'iss' => $serverName, // Issuer 'nbf' => $notBefore, // Not before 'exp' => $expire, // Expire 'data' => [ // Data related to the signer user 'userId' => $rs['id'], // userid from the users table 'userName' => $username, // User name ]
  26. JWT Please notice that you can define the data structure however you want, there are however some reserved claims, such as the ones used above: iat – timestamp of token issuing. jti – A unique string, could be used to validate a token, but goes against not having a centralized issuer authority. iss – A string containing the name or identifier of the issuer application. Can be a domain name and can be used to discard tokens from other applications. nbf – Timestamp of when the token should start being considered valid. Should be equal to or greater than iat. In this case, the token will begin to be valid 10 seconds after being issued. exp – Timestamp of when the token should cease to be valid. Should be greater than iat and nbf. In this case, the token will expire 60 seconds after being issued.
  27. JWTTransforming this array into a JWT is super easy: $secretKey = base64_decode($config->get('jwtKey')); /* * Encode the array to a JWT string. * Second parameter is the key to encode the token. * * The output string can be validated at */ $jwt = JWT::encode( $data, //Data to be encoded in the JWT $secretKey, // The signing key 'HS512' // Algorithm used to sign the token, see algorithms-40#section-3 ); $unencodedArray = ['jwt' => $jwt]; echo json_encode($unencodedArray);
  28. Data Design and Abstraction Planning how your API will look begins earlier than you’d think; first you need to decide how your data will be designed and how your core service / application will work. If you’re doing API First Development this should be easy. If you’re attaching an API to an existing project, you may need to provide more abstraction. Occasionally, a Collection can represent a database table, and a Resource can represent a row within that table. However, this is not the usual case. In fact, your API should abstract away as much of your data and business logic as possible. There are also many parts of your service which you SHOULD NOT expose via API at all. A common example is that many APIs will not allow third parties to create users.
  29. Verbs Surely you know about GET and POST requests. These are the two most commonly used requests when your browser visits different webpages. The term POST is so popular that it has even invaded common language, where people who know nothing about how the Internet works do know they can “post” something on a friends Facebook wall. There are four and a half very important HTTP verbs that you need to know about. I say “and a half”, because the PATCH verb is very similar to the PUT verb, and two two are often combined by many an API developer. Here are the verbs, and next to them are their associated database call. GET (SELECT): Retrieve a specific Resource from the Server, or a listing of Resources. POST (CREATE): Create a new Resource on the Server. PUT (UPDATE): Update a Resource on the Server, providing the entire Resource. PATCH (UPDATE): Update a Resource on the Server, providing only changed attributes. DELETE (DELETE): Remove a Resource from the Server.
  30. Verbs Route::put('user/{id}', 'UserController@update'); Route::get('/', function (Request $request) { // }); Route::delete('foo/bar', function() { // });
  31. Versioning No matter what you are building, no matter how much planning you do beforehand, your core application is going to change, your data relationships will change, attributes will invariably be added and removed from your Resources. This is just how software development works, and is especially true if your project is alive and used by many people (which is likely the case if you’re building an API).
  32. Versioning Planning ahead to ensure your software can evolve along with the rest of the tech world is even more essential when you’re developing an API. Once an API is published, it’s frozen. You can’t change that original code, or you’ll mess everyone up who has plugged into the API. So you create versions, build the right tests to give you confidence that the versions will work, and live by RAD (Rapid Application Development) so that you don’t spin too many wheels before seeing human interactions with your code.
  33. What is the correct way to version my API? The "URL" way A commonly used way to version your API is to add a version number in the URL. For instance: /api/v1/article/1234 To "move" to another API, one could increase the version number: /api/v2/article/1234
  34. Endpoints An Endpoint is a URL within your API which points to a specific Resource or a Collection of Resources. If you were building a fictional API to represent several different Zoo’s, each containing many Animals (with an animal belonging to exactly one Zoo), employees (who can work at multiple zoos) and keeping track of the species of each animal, you might have the following endpoints: HTTP Request header. GET /zoos: List all Zoos (ID and Name, not too much detail) POST /zoos: Create a new Zoo GET /zoos/ZID: Retrieve an entire Zoo object PUT /zoos/ZID: Update a Zoo (entire object) PATCH /zoos/ZID: Update a Zoo (partial object) DELETE /zoos/ZID: Delete a Zoo GET /zoos/ZID/animals: Retrieve a listing of Animals (ID and Name). GET /animals: List all Animals (ID and Name). POST /animals: Create a new Animal
  35. Endpoints
  36. Filtering
  37. Filtering When a Consumer makes a request for a listing of objects, it is important that you give them a list of every single object matching the requested criteria. This list could be massive. But, it is important that you don’t perform any arbitrary limitations of the data. It is important, however, that you do offer the ability for a Consumer to specify some sort of filtering/limitation of the results. The most important reason for this is that the network activity is minimal and the Consumer gets their results back as soon as possible. The second most important reason for this is the Consumer may be lazy, and if the Server can do filtering and pagination for them, all the better. The not-so-important reason (from the Consumers perspective), yet a great benefit for the Server, is that the request will be less resource heavy.
  38. Filtering Filtering is mostly useful for performing GETs on Collections of resources. Since these are GET requests, filtering information should be passed via the URL. Here are some examples of the types of filtering you could conceivably add to your API: l?limit=10: Reduce the number of results returned to the Consumer (for Pagination) l?offset=10: Send sets of information to the Consumer (for Pagination) l?animal_type_id=1: Filter records which match the following condition (WHERE animal_type_id = 1) l?sortby=name&order=asc: Sort the results based on the specified attribute (ORDER BY name ASC)
  39. Swagger The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service. Technically speaking - Swagger is a formal specification surrounded by a large ecosystem of tools, which includes everything from front-end user interfaces, low-level code libraries and commercial API management solutions.
  40. Swagger-PHP A complete framework for "describing, producing, consuming, and visualizing RESTful web services." Swagger-PHP is a PHP annotations library for generating Swagger compatible JSON documentation for your API. The resulting JSON documentation may then be utilized for internal and external user friendly documentation, API portal sandbox with Swagger UI as well as client code generation with the Swagger Code Generation tooling.
  41. Swagger
  42. Rest API Client Advanced REST client client/hgmloofddffdnphfgcellkdfbfbjeloo Postman =en
  43. Thank You