search

calcom / cal.com

Scheduling infrastructure for absolutely everyone.
https://cal.com
Other
31.21k stars 7.53k forks source link

RFC: admin panel (console.cal.com) & Public API #1594

Closed PeerRich closed 2 years ago

PeerRich commented 2 years ago

RFC summary of the recent discussions and feature requests of our slack channel #admin-panel-and-api

RFC: admin panel (console.cal.com) & Public API

Goals:

Who this is for

Who this is not for

planned features

written by @agustif

Started working already on the API, sharing here a first draft of CRUD endpoints needed to start working on admin functionality.

I think those are the biggest models we have and basically with them and extra relations that can be included on a prisma call, we should be able to cover a lot of ground. Let's go for it.

@emrysal would love a little chat about availabilities, or maybe your general inputs about it before building much there, which API func should be useful there, a general CRUD for both schedules and availabilites?

CRUD Endpoints

All endpoints will require Auth. You'll only be able to access the resources you're an owner / team manager of.

Users

GET     /users        : Get all users/
POST    /users        : Create a new user
GET     /users/{id}   : Get the user information identified by "id"
PUT     /users/{id}   : Update the user information identified by "id"
DELETE  /users/{id}   : Delete user by "id"

Event Types

GET     /event-types        : Get all event-types
POST    /event-types        : Create a new event-type
GET     /event-types/{id}   : Get the event-type information identified by "id"
PUT     /event-types/{id}   : Update the event-type information identified by "id"
DELETE  /event-types/{id}   : Delete event-type by "id"

Bookings


GET     /bookings        : Get all bookings
POST    /bookings        : Create a new booking
GET     /bookings/{id}   : Get the booking information identified by "id"
PUT     /bookings/{id}   : Update the booking information identified by "id"
DELETE  /bookings/{id}   : Delete booking by "id"

Availabilites and Schedules

/availabilties ...

/schedules ...

zomars commented 2 years ago

Public API

Now that we have Monorepo, @baileypumfleet and I were discussing on how can we proceed with public API project. Here are my thoughts.

Requirements

Tech Stack

These are the options that come to mind:

...WIP

denik1981 commented 2 years ago

Thanks for the proposal and the later summary. I vote up for Express.

PeerRich commented 2 years ago

i used strapi in the past and quite liked it

zomars commented 2 years ago

i used strapi in the past and quite liked it

I think Strapi is more CMS-focused. I could be wrong tho.

PeerRich commented 2 years ago

i used strapi in the past and quite liked it

I think Strapi is more CMS-focused. I could be wrong tho.

yeh probably a bad usecase to use it

agustif commented 2 years ago

i used strapi in the past and quite liked it

I think Strapi is more CMS-focused. I could be wrong tho.

yeh probably a bad usecase to use it

I was gonna -1 it (for public api)because I had some drama it only supporting integers for prices on an e-commerce once.

I think strapi is more a candidate for an integration maybe down the road although that does seem far fetched! Who knows where the app store will take us 🚀🚀.

For public API I like both Next and express, although separating it into it's own app feels off (although I think nextjs, recently added better support for such kinda redirects)

All in all I would love to know more of what the community thinks would be the best approach for us to follow.

One question I have is how we'll handle auth for the API? Personal Access Tokens? Is Oauth with something like ORY's hydra package too far fetched? It would make a sign in with cal.com closer.

Can we get away for now with just using our current api endpoints in nextjs. But making them compatible with the outside world? Documenting them etc. maybe we can use the new next 12 middleware that next-auth has for the API endpoints?

https://next-auth.js.org/configuration/nextjs

baileypumfleet commented 2 years ago

The idea (for now) is to use personal access tokens, and later we can extend to OAuth support for third-party apps to build on top of the Cal.com API.

I wouldn't mind having the API as part of the next project. Alternatively, I think a separate project makes it cleaner, and especially now that we have the shared Prisma logic libraries and such, it should make it easier. I'm totally open to both options.

The main thing though is that the public API will likely be an enterprise only feature, so this will need to be a private app in the monorepo

denik1981 commented 2 years ago

I'm quite a fan of next but its main use case I think falls outside of building an API. I'm not saying you cannot build one and I believe the argument from @agustif is a valid one meaning that the whole codebase is already driven by Nextjs, but at the same time, I believe using a backend option like Express will embrace much more power to Cal than the limitations you will find with next. Also, Turbo makes everything easier to manage.

PeerRich commented 2 years ago

👍 to pure Express

manjufy commented 2 years ago

The idea (for now) is to use personal access tokens, and later we can extend to OAuth support for third-party apps to build on top of the Cal.com API.

I wouldn't mind having the API as part of the next project. Alternatively, I think a separate project makes it cleaner, and especially now that we have the shared Prisma logic libraries and such, it should make it easier. I'm totally open to both options.

The main thing though is that the public API will likely be an enterprise only feature, so this will need to be a private app in the monorepo

I second to have API separated from the next. Right now, UI + Prisma logic that powers API are tightly coupled.

agustif commented 2 years ago

Started working already on the API, sharing here a first draft of CRUD endpoints needed to start working on admin functionality.

I think those are the biggest models we have and basically with them and extra relations that can be included on a prisma call, we should be able to cover a lot of ground. Let's go for it.

@emrysal would love a little chat about availabilities, or maybe your general inputs about it before building much there, which API func should be useful there, a general CRUD for both schedules and availabilites?

CRUD Endpoints

All endpoints will require Auth. You'll only be able to access the resources you're an owner / team manager of.

Users

GET /users : Get all users/ POST /users : Create a new user GET /users/{id} : Get the user information identified by "id" PUT /users/{id} : Update the user information identified by "id" DELETE /users/{id} : Delete user by "id"

Event Types

GET /event-types : Get all event-types POST /event-types : Create a new event-type GET /event-types/{id} : Get the event-type information identified by "id" PUT /event-types/{id} : Update the event-type information identified by "id" DELETE /event-types/{id} : Delete event-type by "id"

Bookings

GET /bookings : Get all bookings POST /bookings : Create a new booking GET /bookings/{id} : Get the booking information identified by "id" PUT /bookings/{id} : Update the booking information identified by "id" DELETE /bookings/{id} : Delete booking by "id"

Availabilites and Schedules

/availabilties ...

/schedules ...

raro42 commented 2 years ago

I am using Django for REST API backend. It works incredibly well. Can only recommend.

Pls. think about providing a URL with documentation right from the API code without requiring authentication. PUT and DELETE are methods that are often blocked per default in big corps firewall rules. Would limit to only use POST and GET. Translates into: POST /bookings/update/{id} or ... GET /bookings/delete/{id} ... which makes it also more readable in networks trace or developer tools.

About team management:

You'll only be able to access the resources you're an owner / team manager of. That's cool.

How do I add/change a booking where I am the client and not member of the team? You should probably have some hashes or tokens here.

alannnc commented 2 years ago

For the last year I've used NestJs for api, it's pretty solid. It has Express under the hood, and what I really liked it leaves you with a very good architecture. https://docs.nestjs.com/

denik1981 commented 2 years ago

@raro42 this is closed-source. At first, it leads to confusion for me as well. I cannot say enough about this but in terms of cost you would want to keep your stack close to what your crew can manage. Django is Python. Most Cal devs are TS devs.

zomars commented 2 years ago

Expanding on what @denik1981 said, we're going to use NextJS api routes in a new project for that same reason.

StitiFatah commented 2 years ago

I am using Django for REST API backend. It works incredibly well. Can only recommend.

Pls. think about providing a URL with documentation right from the API code with requiring authentication. PUT and DELETE are methods that are often blocked per default in big corps firewall rules. Would limit to only use POST and GET. Translates into: POST /bookings/update/{id} or ... GET /bookings/delete/{id} ... which makes it also more readable in networks trace or developer tools.

About team management:

You'll only be able to access the resources you're an owner / team manager of. That's cool.

How do I add/change a booking where I am the client and not member of the team? You should probably have some hashes or tokens here.

If they wanted to go with the Django Rest Framewrok + React Stack I guess they would have used it directly from the start instead of using Prisma, I've never tried Prisma but I guess it's being used as an ORM for postgres and Django's ORM is maybe one of its biggest strength + it also has a customizable GUI admon dashboard for database operations.

StitiFatah commented 2 years ago

@raro42 this is closed-source. At first, it leads to confusion for me as well. I cannot say enough about this but in terms of cost you would want to keep your stack close to what your crew can manage. Django is Python. Most Cal devs are TS devs.

Are the api endpoints going to be closed source too or only the admin UI letting people build their own dashboards ?

PeerRich commented 2 years ago

@raro42 this is closed-source. At first, it leads to confusion for me as well. I cannot say enough about this but in terms of cost you would want to keep your stack close to what your crew can manage. Django is Python. Most Cal devs are TS devs.

Are the api endpoints going to be closed source too or only the admin UI letting people build their own dashboards ?

@agustif can post the new update here too

compgeniuses commented 2 years ago

Looking forward to this functionality

dsinghvi commented 2 years ago

Will you be creating SDKs in other languages (java/python)? Or will there be a detailed api spec so that we can write community managed ones?

compgeniuses commented 2 years ago

Congratulation on releasing the new API, and the Series A funding.

I see that the Dashboard missed the Launch window. Hopping its available in the next release. Cool stuff seeing youre building Cacom to be the Defactor Platform for calendar and Appointment booking. this will surely drive growth onto the platform.

Also, consider adding more Integration with Opensource Products, Like, Matrix/element, RocketChat, Mattermost and etc

agustif commented 2 years ago

Will you be creating SDKs in other languages (java/python)? Or will there be a detailed api spec so that we can write community managed ones?

The api spec is here: https://docs.cal.com/api Currently a WIP, will be improving it during the weekend and following week. Working on having an alpha release soon so you can all start testing and calling the API.

I think swagger-ui will let us auto-generate snippets for each operation in different languages, but for now we'll focus on API itself, we can improve this later.

I'm really excited to be sharing more news soon, will do a loom demoing the new api keys functionality in webapp, and basically how to get started with API getting a Key and calling the endpoints.

Have a nice weekend everyone!

And yeah dashboard is up next for sure!

agustif commented 2 years ago

Will you be creating SDKs in other languages (java/python)? Or will there be a detailed api spec so that we can write community managed ones?

https://github.com/calcom/cal.com/pull/2547 when this one merges at least snippets will be in more languages than just curl (added java and python in there ;)) using openapi-snippets so anything availabile in there is game, but too many snippets makes the layout break

compgeniuses commented 2 years ago

would the Dashboard and API be available on the self hostable Edition?

PeerRich commented 2 years ago

would the Dashboard and API be available on the self hostable Edition?

for now it'll stay a commercial, closed source feature but the API end points will be publicly accessible and you can generate an API token to authorize against here: https://app.cal.com/settings/security

PeerRich commented 2 years ago

you can receive access to the private API repo to self-host on a commercial plan

compgeniuses commented 2 years ago

so both Dashboard, as well as API would be Enterprise edition only features?

PeerRich commented 2 years ago

you will be able to use them, just the source code will be closed source for now. enterprise can access code

jlalmes commented 2 years ago

@PeerRich: 👍 to pure Express

👀 https://github.com/jlalmes/trpc-openapi

Ping me if you want to chat anything through/any assistance!

zomars commented 2 years ago

@PeerRich: 👍 to pure Express

👀 https://github.com/jlalmes/trpc-openapi

Ping me if you want to chat anything through/any assistance!

It's on the roadmap definitely @jlalmes we need to extract tRPC to a monorepo package, put remaining logic there and there we can adopt it in the open API