seitime-frappe/frappe/docs/user/en/guides/integration/rest_api.md

REST API

Frappé ships with an HTTP API. There are two parts of this API.

1. Remote Procedure Calls (RPC)
2. REST

1. RPC

A request to an endpoint /api/method/{dotted.path.to.function} will call a whitelisted python function. A function can be whitelisted using the frappe.whitelist decorator.

For example, Add the following to sample_app/__init__.py

@frappe.whitelist(allow_guest=True)
def ping():
	return 'pong'

GET http://frappe.local:8000**/api/method/sample_app.ping**

Response:

{
  "message": "pong"
}

2. REST

All documents in Frappé are available via a RESTful API with prefix /api/resource/.

Login

To login, you will have to send a POST request to the login method.

POST http://frappe.local:8000**/api/method/login**

usr=Administrator&pwd=admin

Response:

{
   "full_name": "Administrator",
   "message": "Logged In"
}

Try to make an authenticated request

GET http://frappe.local:8000**/api/method/frappe.auth.get_logged_user**

Response:

{
   "message": "Administrator"
}

Listing Documents

To list documents, the URL endpoint is /api/resource/{doctype} and the expected HTTP verb is GET.

Response is returned as JSON Object and the listing is an array in with the key data.

GET http://frappe.local:8000**/api/resource/Person**

Response:

{
   "data": [
	  {
		 "name": "000000012"
	  },
	  {
		 "name": "000000008"
	  }
   ]
}

Fields

By default, only name field is included in the listing, to add more fields, you can pass the fields param to GET request. The param has to be a JSON array.

GET http://frappe.local:8000**/api/resource/Person/?fields=["name", "first_name"]**

Response:

{
   "data": [
	  {
		 "first_name": "Jane",
		 "name": "000000012"
	  },
	  {
		 "first_name": "John",
		 "name": "000000008"
	  }
   ]
}

Filters

You can filter the listing using sql conditions by passing them as the filters GET param. Each condition is an array of the format, [{doctype}, {field}, {operator}, {operand}].

Eg, to filter persons with name Jane, pass a param filters=[["Person", "first_name", "=", "Jane"]]

GET http://frappe.local:8000**/api/resource/Person/**

Response: { "data": [ { "name": "000000012" } ] }

Pagination

All listings are returned paginated by 20 items. To change the page size, you can pass limit_page_length. To request succesive pages, pass limit_start as per your limit_page_length.

For Example, to request second page, pass limit_start as 20.

GET http://frappe.local:8000**/api/resource/DocType**

Response:

{
   "data": [
	  {
		 "name": "testdoc"
	  },
	  {
		 "name": "Person"
	  },

	  ......

	  {
		 "name": "Website Template"
	  }
   ]
}

GET http://frappe.local:8000**/api/resource/DocType?limit_start=20**

Response:

{
   "data": [
	  {
		 "name": "Website Route"
	  },
	  {
		 "name": "Version"
	  },
	  {
		 "name": "Blog Post"
	  },

	  ......

	  {
		 "name": "Custom Field"
	  }
   ]
}

CRUD

Create

You can create a document by sending a POST request to the url, /api/resource/{doctype}.

POST http://frappe.local:8000**/api/resource/Person**

Body:

data={"first_name": "Robert"}

Response:

{
  "data": {
	"first_name": "Robert",
	"last_name": null,
	"modified_by": "Administrator",
	"name": "000000051",
	"parent": null,
	"creation": "2014-05-04 17:22:38.037685",
	"modified": "2014-05-04 17:22:38.037685",
	"doctype": "Person",
	"idx": null,
	"parenttype": null,
	"owner": "Administrator",
	"docstatus": 0,
	"parentfield": null
  }
}

Read

You can get a document by its name using the url, /api/resource/{doctype}/{name}

For Example,

GET http://frappe.local:8000**/api/resource/Person/000000012**

Response:

{
  "data": {
	"first_name": "Jane",
	"last_name": "Doe",
	"modified_by": "Administrator",
	"name": "000000012",
	"parent": null,
	"creation": "2014-04-25 17:56:51.105372",
	"modified": "2014-04-25 17:56:51.105372",
	"doctype": "Person",
	"idx": null,
	"parenttype": null,
	"owner": "Administrator",
	"docstatus": 0,
	"parentfield": null
  }
}

Update

You can create a document by sending a PUT request to the url, /api/resource/{doctype}. This acts like a PATCH HTTP request in which you do not have to send the whole document but only the parts you want to change.

For Example,

PUT http://frappe.local:8000**/api/resource/Person/000000008**

Body:

data={"last_name": "Watson"}

Response:

{
  "data": {
	"first_name": "John ",
	"last_name": "Watson",
	"modified_by": "Administrator",
	"name": "000000008",
	"creation": "2014-04-25 17:26:22.728327",
	"modified": "2014-05-04 18:21:45.385995",
	"doctype": "Person",
	"owner": "Administrator",
	"docstatus": 0
  }
}

Delete

You can delete a document by its name by sending a DELETE request to the url, /api/resource/{doctype}/{name}.

For Example,

DELETE http://frappe.local:8000**/api/resource/Person/000000008**

Response:

{"message":"ok"}