Choosing an API

Editor's Notes

• #3: Sometimes when you start talking about APIs, it can get like a religious war. My suggestion is that instead of thinking of it in regards to one being better than another, you need to think in terms of what you are trying to accomplish and what will best meet those needs.
• #4: Just because something is newer, doesn’t necessarily mean it is better.
• #5: Remote Procedure Call (RPC) is a protocol that one program can use to request a service from a program located in another computer on a network without having to understand the network's details. When implemented in http, it is a web api. Includes xml-rpc and soap
• #6: From the consumers standpoint, they are simple to understand and use since you just make a function call passing in parameters. However, if you are using SOAP and trying to create an RPC endpoint without tooling, it can be difficult. Lighter payloads somewhat depends on if you are using SOAP. The SOAP envelope adds some weight. It also depends on the size of your REST resources you are comparing it to as requests will return an entire resource, not just the part you may be interested in.
• #8: REST is a network paradigm described by Roy Fielding in a dissertation in 2000. REST is all about a client-server relationship, where server-side data are made available through representations of data in simple formats. This format is usually JSON or XML but could be anything. Actions and relationships may be made discoverable via a concept known as hypermedia controls (HATEOAS). This is a powerful yet often ignored feature of REST. REST must be stateless. Responses should declare cacheablility since it helps your API scale if clients respect the rules. This can be set by the normal http means such as Expires headers. Uniformity and consistency is important in your REST API. Iif you’re using HTTP you should utilize HTTP features whenever possible, instead of inventing conventions Odata and JSON-API are examples of REST standards
• #9: REST is dealing with things from the point of resources. They are described as nouns. Easy to build because no toolkits are required and the output is human readable
• #10: It is an architectural pattern rather than a single spec. HAL (Hypertext Application Language), HAETOAS, Ion, Json-API, Odata A couple months ago when I did the presentation on REST, you may have noticed that most people using REST did it differently and were not using all the verbs as suggested.
• #11: GraphQL is essentially RPC, with a lot of good ideas from the REST/HTTP community tacked in. It is one of the fastest growing API ecosystems out there It is a standard that allows the client application to use a query to request exactly the desired data. You ask for specific resources and specific fields, and it will return that data in the response. You can also create mutations to add or update data and you can create subscriptions so that when data changes or specific events happen the subscribers are notified. It allows the front-end developer, to write queries that have the exact data shape they want. In addition to allowing fewer data elements to be returned in a query, it also reduces the number of HTTP requests necessary to retrieve data for multiple resources. With REST APIs, you may get a list of customers in one call and then have to make individual calls for each customer to get their orders. All of these individual calls are much slower than the single call that can be made with GraphQL.
• #12: Left side shows the GraphQL query and the right side shows the json response
• #13: The lower bandwidth is very important to mobile devices Only return the desired data elements instead of all of them. No over or under fetching data. Underfetching => n+1 issue It can batch queries so that it is returned in one package rather than having to make multiple queries to the server. Talk about a blog: Post, author info, comments With the variety of different mobile and web devices, you may have different data being returned to different devices. You can add data elements to the schema on the server without having to worry about versioning. When new elements are added, old clients will still work since they aren’t using these. Removing items is a different matter. A common pattern with REST APIs is to structure the endpoints according to the views that you have inside your app. This is handy since it allows for the client to get all required information for a particular view by simply accessing the corresponding endpoint. The major drawback of this approach is that it doesn’t allow for rapid iterations on the frontend. With every change that is made to the UI, there is a high risk that there will be more (or less) data required than before. This results in the backend having to be adjusted to account for the new data needs. This approach requires both front and backend development. When using GraphQL, if the database already includes the desired information, all of the changes can be made on the client.
• #14: By using the Apollo client, you can overcome some of the complexity and get caching included.
• #18: What makes it seem even more complex for .NET developers is that there aren’t a lot of good, working examples. There are even fewer that use the latest versions of .NET Core and other framework elelments.
• #20: REST discoverability is good if it is implemented properly. I see few REST APIs where this is the case.
• #21: While there is no guidance on GraphQL versioning, this may not be a negative as the client has more control of the shape of data they are retrieving.