Skyward.Api.Popcorn 7.3.2

dotnet add package Skyward.Api.Popcorn --version 7.3.2                
NuGet\Install-Package Skyward.Api.Popcorn -Version 7.3.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Skyward.Api.Popcorn" Version="7.3.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Skyward.Api.Popcorn --version 7.3.2                
#r "nuget: Skyward.Api.Popcorn, 7.3.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Skyward.Api.Popcorn as a Cake Addin
#addin nuget:?package=Skyward.Api.Popcorn&version=7.3.2

// Install Skyward.Api.Popcorn as a Cake Tool
#tool nuget:?package=Skyward.Api.Popcorn&version=7.3.2                

<img src="/media/PopcornLogo.png" width="50%">

Popcorn

Join the chat at https://gitter.im/popcorn-api/Lobby Build status NuGet

Table Of Contents

Jump straight in

  • .NET Core - We have a .net core middleware that you can drop in to enable Popcorn on Web Apis. Feel free to grab it on nuget.
  • Other implementations - See our Roadmap or issues on GitHub for coming work

What is Popcorn?

Popcorn is a communication protocol on top of a RESTful API that allows requesting clients to identify individual fields of resources to include when retrieving the resource or resource collection.

It allows for a recursive selection of fields, allowing multiple calls to be condensed into one.

Features

Ok, so.... what is it in action?

Okay, maybe some examples will help!

Lets say you have a REST API with an endpoint like so:

https://myserver.com/api/1/contacts

Which returns a list of contacts in the form:

[
 {
   "Id":1,
   "Name":"Liz Lemon"
 },
 {
   "Id":2,
   "Name":"Pete Hornberger"
 },
 {
   "Id":3,
   "Name":"Jack Donaghy"
 },
 ...
}

Now, if you want to get a list of phone numbers for each of those, you now need to make a series of calls to further endpoints, one for each contact you want to look up the information for:

https://myserver.com/api/1/contacts/1/phonenumbers

[
  {"Type":"cell","Number":"867-5309"}
]

https://myserver.com/api/1/contacts/2/phonenumbers

[
  {"Type":"landline","Number":"555-5555"}
]

https://myserver.com/api/1/contacts/3/phonenumbers

[
  {"Type":"cell","Number":"123-4567"}
]

That's quite a lot of overhead and work! Popcorn aims to simplify this at the client's request. Let's say that while we want the numbers for each contact, we don't really need the type of the number (cell or landline) and would prefer to save the bandwidth by not transfering it. Now, instead of making many calls, all the above can be reduced down to:

https://myserver.com/api/1/contacts?include=[Id,Name,PhoneNumbers[Number]]

Which provides:

[
 {
    
   "Id":1,
   "Name":"Liz Lemon",
   "PhoneNumbers":
   [
    {
     "Number":"867-5309"
    }
   ]
 },
 {
   "Id":2,
   "Name":"Pete Hornberger",
   "PhoneNumbers":
   [
    {
     "Number":"555-5555"
    }
   ]
 },
 {
   "Id":3,
   "Name": "Jack Donaghy",
   "PhoneNumbers":
   [
    {
     "Number":"123-4567"
    }
   ]
 },
 ...
}

Presto! All the information we wanted at our fingertips, and none of the data we didn't!

Why would I use it?

By implementing the Popcorn protocol, you get a consistent, well defined API abstraction that your API consumers will be able to easily utilize. You will be able to take advantage of the various libraries and tools Popcorn offers; right now this includes a C# automatic implementation for Asp.Net Core and EntityFramework Core, but many more platforms are on the roadmap.

Pros

  • Faster calls
  • Saves data
  • Potential for server-side optimization
  • Less boilerplate code to write

Cons

  • You don't get to write as much code
  • Your consumers don't get to write as much code

How can I use it in my project?

First you need to figure out if you're working with a platform that has a provider implemented in the popcorn project. (Probably check out Documentation).

If there's a provider already in the project, great! The platform-specific documentation will walk you though incorporating the provider into your project.

If there isn't a provider yet, you'll have to roll your own. You'll still get the benefit of working with a standard, so your consumers will have a well documented spec to work with. Feel free to contribute any platform-specific providers you come up with!

Further Reading

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Skyward.Api.Popcorn:

Package Downloads
Skyward.Api.Popcorn.WebApiCore

WebApi extensions to Popcorn

Skyward.Api.Popcorn.EntityFrameworkCore

EntityFrameworkCore extensions to Popcorn

Skyward.Api.Popcorn.WebApi5

.Net 5 WebApi extensions to Popcorn

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
7.3.2 167 5/22/2024
6.2.3 2,347 2/27/2023
5.0.0 1,835 7/6/2020
4.7.0 3,857 10/25/2019
4.6.2 923 10/23/2019
4.6.1 1,080 10/23/2019
4.6.0 592 10/23/2019
4.5.2 1,622 8/19/2019
4.4.2 1,820 4/11/2019
4.4.1 1,179 4/9/2019
4.3.1 12,401 11/6/2018
4.0.0 4,684 7/31/2018
3.2.0 1,609 7/18/2018
3.1.0 3,472 3/9/2018
2.0.0 1,243 10/27/2017
1.3.0 1,292 10/12/2017
1.2.0 1,161 10/11/2017
1.1.3 1,095 9/29/2017
1.1.2 1,173 9/1/2017
1.1.1 1,092 8/29/2017
1.1.0 1,106 8/29/2017

Allow re-referencing the same object so long as it is not in a loop.