一、什么是REST API?
REST API是一种网络接口,使用REST API,可以不通过用户界面来进行数据的访问和操作。
使用REST API,可以通过向Salesforce的endpoint发送Http请求来进行数据访问或操作。REST API比SOAP API更简便,且仍然具有很多功能。
二、开启 API Access功能:
要想使用Salesforce的API,需要先开启组织的【API access】和【API Enabled user】权限。
能够开启API Access的Salesforce组织:①Professional Edition;②Performance Edition;③Enterprise Edition;④Unlimited Edition;⑤Developer Edition
注:如果未开启API Access功能而向Salesforce发送API request请求,会返回API_DISABLED_FOR_ORG错误。
三、REST API都能干什么:
指定执行的REST API的版本
查看组织的关于API的限制
查询object的metadata数据(例如表结构)
增删改查数据
查询数据
四、REST API的URI结构:
https://MyDomainName.my.salesforce.com/services/data/vXX.X/resource/
注: (1)使用https://可以安全地访问资源
(2)MyDomainName指的是当前Salesforce组织的sub Domain名
(3)vXX.X为使用的API版本
(4)resource指的是调用的资源(如调用的API名)
(5)URL的部分文字是大小写敏感的,如ID;部分文字是大小写不敏感的,如object名和字段名。
(6)REST API发送的请求支持http的标准请求方式 (HEAD, GET, POST, PATCH, PUT, 和 DELETE)
五、Header:
使用header可以传递参数和自定义http请求设置。
(1)Accept:指定接收的response body的内容类型
可用参数:①application/json(默认) ②application/xml
(2)Content-type:指定response body文件的接收形式和文件编码
可用参数:①application/json ②application/xml
(3)Authorization:提供OAuth 2.0 token来进行认证。Rest API支持Bearer认证方式。
(4)Compression:可压缩request和response。
(5)Conditional request:可以指定想要在response body中获得的信息。
六:Request Body:
Request Body可以用于为request请求添加附加信息,例如新建或更新数据。Request Body
可以使用JSON或XML格式。
注:使用GET方法发送的request请求不需要添加Request Body。
七、关于REST API的其他补充:
(1)访问REST API资源通过使用https方式
(2)REST API支持OAuth 2.0认证方式
(3)REST API支持JSON和XML两种传输方式,默认为JSON,可通过【HTTP ACCEPT】header来设定。
(4)关于REST API的request和response的id位数:
在request中,15位和18位ID均可使用;
在response body中,通常是18位ID。
八、关于OAuth 2.0:
OAuth是一种开放授权,即允许用户授权让第三方应用在特定的时间段来访问自己的资源。用户提供一个令牌,授权让第三方应用来访问,而无需向第三方应用提供用户名和密码。
OAuth 2.0是OAuth的新一代版本,并且不与OAuth 1.0兼容(即废止了OAuth 1.0)。
九、关于http的response 状态码:
1.以“2”开头,表示成功:
(1)200:表示“成功”。通常用于GET、HEAD和一些PATCH中。
(2)201:表示“已创建”。通常用于POST和一些PATCH中。
(3)204:表示“没有内容”。通常用于DELETE和一些PATCH中。
2.以“3”开头,表示重定向:
(1)300:当外部ID存在于多条数据中时返回该状态码。即Response Body中包含多条符合的数据。
(2)304:用户在发送请求的header中指定日期时间,如果从这个日期时间开始请求的文件内容未变化,则返回该状态码。(用于指定日期时间的header是【If-Modified-Since】)
3.以“4”开头,表示客户端错误:
(1)400:请求无法被解析,通常是因为JSON或XML body中有错误。
(2)401:Session ID或OAuth令牌无效或过期,在response body中会有相关信息和错误状态码
(3)403:请求被拒绝。查看发送请求的用户是否有权限。若错误信息是“REQUEST_LIMIT_EXCEEDED”,则是超出了组织API请求上限。
(4)404:找不到请求中的信息。检查URI是否正确。
(5)405:请求行中的方法不被允许访问URI
(6)409:请求无法完成,因为当前请求的相关设定中存在冲突。检查请求的API版本是否合适。
(7)410:通知用户该资源已经不可再用,主要是帮助网站管理员维护网站。
(8)412:表示“未满足前提条件”,如用户发送的请求的header中的指定条件无法对应。
(9)414:URI长度过长(超出16384 byte)
(10)415:服务器无法处理请求附带的媒体格式。检查header中的Content Type是否正确。
(11)431:URI和header加在一起的长度超过16384 byte,可能是由于token过长。
4.以“5”开头,表示服务器错误:
(1)500:Lightning Platform发生错误,请求无法处理。请联系Salesforce服务台。
(2)503:服务器无法处理请求。一般是因为系统维护或超载。
十、Salesforce API的寿命周期:
1.Salesforce的每个版本的API都会提供至少三年的支持服务。
2.Salesforce会逐步废止旧版的API的使用。
3.当你使用已废止的API版本来发送API请求时,会发生410:GONE错误。