Frappe Rest API V2

bkings12 · July 17, 2024, 5:17pm

Where can i get frappe rest api version 2 cause the one in the documentation is version 1.

avc · July 18, 2024, 5:22am

Hi @bkings12:

It’s no documented yet because isn’t totally finished. It’s working on version-15 with limited funcionality.

Some useful info here:

github.com/frappe/frappe

feat!: API versioning and API v2 (beta)

frappe:develop ← ankush:api_v2

opened 12:22PM - 03 Sep 23 UTC

ankush

+1056 -460

### Why? - Versioning lets us improve the way APIs work while still being backw…ard compatible. - We have known few problems with APIs for long time but they can't be easily addressed because they will likely require backward incompatible changes. ### Changes - All API routing is now handled by Werkzeug routing. - New alias for API versions `/api/*` == `/api/v1/` - `/api/v2` prefix for new APIs. - API versions will ONLY specify URL and response structure. - REST APIs will not break between versions. RPC calls and schema are out of the scope of versioning, they CAN change between versions. Keeping them backward compatible is job of developers doing the changes. ### V2 changes and features ##### 1. Shorthand for all whitelisted functions in controller files. ```diff - GET /api/v1/method/erpnext.selling.doctype.sales_order.sales_order.make_sales_invoice + GET /api/v2/method/Sales Order/make_sales_invoice ``` ##### 2. Call whitelisted functions directly on ~~resources~~ => documents. ```diff - POST /api/v1/resource/Sales Order/SO-0001?run_method=submit + POST /api/v2/document/Sales Order/SO-0001/method/submit ``` closes https://github.com/frappe/frappe/issues/14869 ##### 3. Response Structure change - [x] `message` => `data` key for response data **everywhere**. - [x] `errors` key for nested and rich error information, replacing `exc`/`exc_type` etc. closes https://github.com/frappe/frappe/issues/14905 ##### 4. URL/verb differences - PATCH == PUT for updating documents. PATCH is the correct convention for partial updates. - APIs are now divided in 3 types: - `document` - previously known as `resource` - `method` - RPC calls, same as before - `doctype` - new class of APIs that operate on doctype instead of documents. e.g. meta, count, list etc. ### TODO - [x] This PR currently copies a lot of code to demonstrate changes. Rewrite all code that touches v2 APIs before merge. - [x] Merge `handle.py` and `api.py`, remove `globals()` lookups in RPC handler. That's unnecessary special handling. - [x] URL encoding of names - [x] Finalize response structure - [x] Impl Errors and message response structure - [x] Tests for both versions. Aim 100% coverage for this. - [x] Collections should have methods, e.g. `GET /api/resource/Sales Order/method/count`, meta (?) - [x] File creation and attachment - [ ] Update client side code, frappeclient. - [ ] xcall now uses v2 - [x] All message handlers should work Optional / separate PRs. - [ ] Access to actual response object from whitelisted functions. - [ ] frappe.response.header for sending custom headers - [ ] get_value alternate - [ ] Documents should have methods like add attachment, get attachment, add comment, etc - [ ] Bulk update - [ ] permissions ?? - [ ] bulk insert with array - [x] delete child doc - [ ] update js `frappe.db` - [ ] `?expand=["link_field_name"]` to link fields to their linked documents. - [ ] reports via rest api /api/report/name

Hope this helps.

bkings12 · July 18, 2024, 6:00am

Yes this is a good place to start. Thanks.

emransalah · November 21, 2024, 10:06am

Does it ready now?

avc · November 21, 2024, 11:59am

Hi @emransalah:

Still work in progress …

Anyway, REST API V2 is working with limited features.

github.com/frappe/frappe

feat!: API versioning and API v2 (beta)

frappe:develop ← ankush:api_v2

opened 12:22PM - 03 Sep 23 UTC

ankush

+1056 -460

### Why? - Versioning lets us improve the way APIs work while still being backw…ard compatible. - We have known few problems with APIs for long time but they can't be easily addressed because they will likely require backward incompatible changes. ### Changes - All API routing is now handled by Werkzeug routing. - New alias for API versions `/api/*` == `/api/v1/` - `/api/v2` prefix for new APIs. - API versions will ONLY specify URL and response structure. - REST APIs will not break between versions. RPC calls and schema are out of the scope of versioning, they CAN change between versions. Keeping them backward compatible is job of developers doing the changes. ### V2 changes and features ##### 1. Shorthand for all whitelisted functions in controller files. ```diff - GET /api/v1/method/erpnext.selling.doctype.sales_order.sales_order.make_sales_invoice + GET /api/v2/method/Sales Order/make_sales_invoice ``` ##### 2. Call whitelisted functions directly on ~~resources~~ => documents. ```diff - POST /api/v1/resource/Sales Order/SO-0001?run_method=submit + POST /api/v2/document/Sales Order/SO-0001/method/submit ``` closes https://github.com/frappe/frappe/issues/14869 ##### 3. Response Structure change - [x] `message` => `data` key for response data **everywhere**. - [x] `errors` key for nested and rich error information, replacing `exc`/`exc_type` etc. closes https://github.com/frappe/frappe/issues/14905 ##### 4. URL/verb differences - PATCH == PUT for updating documents. PATCH is the correct convention for partial updates. - APIs are now divided in 3 types: - `document` - previously known as `resource` - `method` - RPC calls, same as before - `doctype` - new class of APIs that operate on doctype instead of documents. e.g. meta, count, list etc. ### TODO - [x] This PR currently copies a lot of code to demonstrate changes. Rewrite all code that touches v2 APIs before merge. - [x] Merge `handle.py` and `api.py`, remove `globals()` lookups in RPC handler. That's unnecessary special handling. - [x] URL encoding of names - [x] Finalize response structure - [x] Impl Errors and message response structure - [x] Tests for both versions. Aim 100% coverage for this. - [x] Collections should have methods, e.g. `GET /api/resource/Sales Order/method/count`, meta (?) - [x] File creation and attachment - [ ] Update client side code, frappeclient. - [ ] xcall now uses v2 - [x] All message handlers should work Optional / separate PRs. - [ ] Access to actual response object from whitelisted functions. - [ ] frappe.response.header for sending custom headers - [ ] get_value alternate - [ ] Documents should have methods like add attachment, get attachment, add comment, etc - [ ] Bulk update - [ ] permissions ?? - [ ] bulk insert with array - [x] delete child doc - [ ] update js `frappe.db` - [ ] `?expand=["link_field_name"]` to link fields to their linked documents. - [ ] reports via rest api /api/report/name

Hope this helps.

frappefr · January 14, 2025, 11:45am

feat!: API versioning and API v2 (beta) by ankush · Pull Request #22300 · frappe/frappe · GitHub was closed as resolved on November 1st 2023.
Do we have doc somewhere in 2025?

Peer · January 14, 2025, 12:03pm

Are you sure it’s actually needed?

Reading in: feat!: API versioning and API v2 (beta) by ankush · Pull Request #22300 · frappe/frappe · GitHub

The titles:

Shorthand for all whitelisted functions in controller files.
Call whitelisted functions directly on ~~resources~~ => documents.

I get the impression that the new methods are already part of the documentation, it’s just that the version designation is not included in the URL.

At least I do use them naturally since quite some time already.

So maybe it’s been sneaked into the documentation without us really noticing it.