###### tags: `Presentations` --- slideOptions: transition: slide # Disclaimer (Expertise, ideas, discussion) title: Rest API Presentation & Postman automated testing --- # REST API PRESENTATION ### Content - APIs in general - REST - Best practices - Considerations - Testing - Postman --- ## APIs in general ### APIs Are Like User Interfaces--Just With Different Users in Mind - Software needs an interface that makes it easy to consume data. Enter, application programming interfaces. - APIs are used by software applications in much the same way that interfaces for apps and other software are used by humans. - (Why am I even saying this? To bring up a possibility for a different view on an API) --- ### REST - REST, or REpresentational State Transfer, is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other. REST-compliant systems, often called RESTful systems, are characterized by how they are stateless and separate the concerns of client and serve --- ### Best practices --- #### JSON - REST APIs should accept JSON for request payload and also send responses to JSON. JSON is the standard for transferring data. Almost every networked technology can use it: JavaScript has built-in methods to encode and decode JSON either through the Fetch API or another HTTP client. Server-side technologies have libraries that can decode JSON without doing much work. (Don't forget the content type header) --- #### Naming  --- #### Naming - Use nouns instead of verbs in endpoint paths - We shouldn’t use verbs in our endpoint paths. Instead, we should use the nouns which represent the entity that the endpoint that we’re retrieving or manipulating as the pathname. - Example: - Can we apply the naming principle here ? ``` -lang csharp [HttpGet] [Route("{productGuid:guid}/variants/{cultureCode}")] public async Task<IHttpActionResult> GetVariants( [FromUri] Guid productGuid, [FromUri] string cultureCode, int? limit = Constants.Pagination.DefaultLimit, int? startAt = null, string sort = "") { ``` - HTTP request method already has the verb. Having verbs in our API endpoint paths isn’t useful and it makes it unnecessarily long since it doesn’t convey any new information. The chosen verbs could vary by the developer’s whim. For instance, some like ‘get’ and some like ‘retrieve’, so it’s just better to let the HTTP GET verb tell us what and endpoint does. --- #### Use logical nesting on endpoints - When designing endpoints, it makes sense to group those that contain associated information. That is, if one object can contain another object, you should design the endpoint to reflect that. This is good practice regardless of whether your data is structured like this in your database. In fact, it may be advisable to avoid mirroring your database structure in your endpoints to avoid giving attackers unnecessary information. - Sounds familiar to one of the problems we had recently ? - Example: (Could we apply the principle here?) ``` -lang csharp [RoutePrefix("Ucommerceapi/v2/products")] [HttpGet] [Route("variants/{productGuid:guid}/{cultureCode}")] public IHttpActionResult VariantDetails([FromUri] Guid productGuid, [FromUri] string cultureCode) { ``` --- #### Handling errors - To eliminate confusion for API users when an error occurs, we should handle errors gracefully and return HTTP response codes that indicate what kind of error occurred. This gives maintainers of the API enough information to understand the problem that’s occurred. We don’t want errors to bring down our system, so we can leave them unhandled, which means that the API consumer has to handle them. - Example: (what happens here when there are multiple promotions and we use `SingleOrDefault()`) ``` -lang csharp var promotion = PromotionRepository.SingleOrDefault(x => x.Name == createPromotionRequest.Name && x.Campaign.Guid == campaign.Guid); ``` --- #### Allow filtering, sorting, and pagination - The databases behind a REST API can get very large. Sometimes, there’s so much data that it shouldn’t be returned all at once because it’s way too slow or will bring down our systems. Therefore, we need ways to filter items. - We also need ways to paginate data so that we only return a few results at a time. We don’t want to tie up resources for too long by trying to get all the requested data at once. - Filtering and pagination both increase performance by reducing the usage of server resources. As more data accumulates in the database, the more important these features become. - Example: ``` -lang csharp public async Task<IHttpActionResult> GetProducts( [FromUri] string cultureCode, int? limit = Constants.Pagination.DefaultLimit, int? startAt = null, string searchTerm = "", string sort = "", bool includeVariants = false) { ``` --- #### Versioning - We should have different versions of API if we’re making any changes to them that may break clients. The versioning can be done according to semantic version (for example, 2.0.6 to indicate major version 2 and the sixth patch) like most apps do nowadays. - This way, we can gradually phase out old endpoints instead of forcing everyone to move to the new API at the same time. The v1 endpoint can stay active for people who don’t want to change, while the v2, with its shiny new features, can serve those who are ready to upgrade. This is especially important if our API is public. We should version them so that we won’t break third party apps that use our APIs. - We just add the version number to the start of the endpoint URL path to version them. --- #### Extras - Cache data to improve performance - Maintain good security practices --- ### Issues and considerations based on experience ### Request body on GET - Common issue we lately faced several times - RFC2616 VS RFCs 7230-7237 - `the message-body SHOULD be ignored when handling the request" has been deleted.` - Inspiration from Elastic - Comes with trade-offs such as Caching (yes yet again!), - >Proxies are not going to look in the GET body to see if the parameters have an impact on the response (UNVERIFIED!) --- ## Now the fun part Postman & test - Bad way - Good way - Collection runners - Monitors - CLIs - CLIs with external hosts --- <style> .reveal { font-size: 24px; } </style>