|
| 1 | +# Step-By-Step Guide to a Running API |
| 2 | + |
| 3 | +The most basic use case leverages Entity Framework. |
| 4 | +The shortest path to a running API looks like: |
| 5 | + |
| 6 | +- Create a new web app |
| 7 | +- Install |
| 8 | +- Define models |
| 9 | +- Define the DbContext |
| 10 | +- Define controllers |
| 11 | +- Add Middleware and Services |
| 12 | +- Seed the database |
| 13 | +- Start the app |
| 14 | + |
| 15 | +This page will walk you through the **simplest** use case. More detailed examples can be found in the detailed usage subsections. |
| 16 | + |
| 17 | +### Create A New Web App |
| 18 | + |
| 19 | +``` |
| 20 | +mkdir MyApp |
| 21 | +cd MyApp |
| 22 | +dotnet new webapi |
| 23 | +``` |
| 24 | + |
| 25 | +### Install |
| 26 | + |
| 27 | +``` |
| 28 | +dotnet add package JsonApiDotnetCore |
| 29 | +
|
| 30 | +- or - |
| 31 | +
|
| 32 | +Install-Package JsonApiDotnetCore |
| 33 | +``` |
| 34 | + |
| 35 | +### Define Models |
| 36 | + |
| 37 | +Define your domain models such that they implement `IIdentifiable<TId>`. |
| 38 | +The easiest way to do this is to inherit `Identifiable` |
| 39 | + |
| 40 | +```c# |
| 41 | +public class Person : Identifiable |
| 42 | +{ |
| 43 | + [Attr("name")] |
| 44 | + public string Name { get; set; } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +### Define DbContext |
| 49 | + |
| 50 | +Nothing special here, just an ordinary `DbContext` |
| 51 | + |
| 52 | +``` |
| 53 | +public class AppDbContext : DbContext |
| 54 | +{ |
| 55 | + public AppDbContext(DbContextOptions<AppDbContext> options) |
| 56 | + : base(options) { } |
| 57 | + |
| 58 | + public DbSet<Person> People { get; set; } |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +### Define Controllers |
| 63 | + |
| 64 | +You need to create controllers that inherit from `JsonApiController<TEntity>` or `JsonApiController<TEntity, TId>` |
| 65 | +where `TEntity` is the model that inherits from `Identifiable<TId>` |
| 66 | + |
| 67 | +```c# |
| 68 | +public class PeopleController : JsonApiController<Person> |
| 69 | +{ |
| 70 | + public PeopleController( |
| 71 | + IJsonApiContext jsonApiContext, |
| 72 | + IResourceService<Person> resourceService, |
| 73 | + ILoggerFactory loggerFactory) |
| 74 | + : base(jsonApiContext, resourceService, loggerFactory) |
| 75 | + { } |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +### Middleware and Services |
| 80 | + |
| 81 | +Finally, add the services by adding the following to your Startup.ConfigureServices: |
| 82 | + |
| 83 | +```c# |
| 84 | +public IServiceProvider ConfigureServices(IServiceCollection services) |
| 85 | +{ |
| 86 | + // add the db context like you normally would |
| 87 | + services.AddDbContext<AppDbContext>(options => |
| 88 | + { // use whatever provider you want, this is just an example |
| 89 | + options.UseNpgsql(GetDbConnectionString()); |
| 90 | + }, ServiceLifetime.Transient); |
| 91 | + |
| 92 | + // add jsonapi dotnet core |
| 93 | + services.AddJsonApi<AppDbContext>(); |
| 94 | + // ... |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +Add the middleware to the Startup.Configure method. Note that under the hood, |
| 99 | +this will call `app.UseMvc()` so there is no need to add that as well. |
| 100 | + |
| 101 | +```c# |
| 102 | +public void Configure(IApplicationBuilder app) |
| 103 | +{ |
| 104 | + app.UseJsonApi(); |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +### Seeding the Database |
| 109 | + |
| 110 | +One way to seed the database is in your Configure method: |
| 111 | + |
| 112 | +```c# |
| 113 | +public void Configure( |
| 114 | + IApplicationBuilder app, |
| 115 | + AppDbContext context) |
| 116 | +{ |
| 117 | + context.Database.EnsureCreated(); |
| 118 | + if(context.People.Any() == false) |
| 119 | + { |
| 120 | + context.People.Add(new Person { |
| 121 | + Name = "John Doe" |
| 122 | + }); |
| 123 | + context.SaveChanges(); |
| 124 | + } |
| 125 | + // ... |
| 126 | + app.UseJsonApi(); |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +### Start the App |
| 131 | + |
| 132 | +``` |
| 133 | +dotnet run |
| 134 | +curl http://localhost:5000/people |
| 135 | +``` |
| 136 | + |
0 commit comments