简体   繁体   English

有关解决API的REST资源的建议

[英]Suggestions on addressing REST resources for API

I'm a new REST convert and I'm trying to design my first RESTful (hopefully) api and here is my question about addressing resources 我是一个新的REST转换者,我正在尝试设计我的第一个RESTful(希望如此)api,这是我关于解决资源的问题

Some notes first: 首先注意一些事项:

  • The data described here are 3d render jobs 此处描述的数据是3d渲染作业
  • A user (graphics company) has multiple projects. 一个用户(图形公司)有多个项目。
  • A project has multiple render jobs. 一个项目有多个渲染作业。
  • A render job has multiple frames. 渲染作业具有多个框架。
  • There is a hierarchy enforced in the data (1 render job belongs to one project, to one user) 数据中强制执行一个层次结构(1个渲染作业属于一个项目,属于一个用户)

How's this for naming my resourses...? 这如何命名我的资源...?

https:/api.myrenderjobsite.com/

/users/graphicscompany/projects
/users/graphicscompany/projects/112233
/users/graphicscompany/projects/112233/renders/
/users/graphicscompany/projects/112233/renders/889900
/users/graphicscompany/projects/112233/renders/889900/frames/0004

OR a shortened address for renders? 或缩短渲染地址?

/users/graphicscompany/renders/889900
/users/graphicscompany/renders/889900/frames/0004

OR should I shorten (even more) the address if possible, omitting the user when not needed...? 或者如果可能的话,我应该缩短(甚至更多)地址,在不需要时省略用户...吗?

/projects/112233/
/renders/889900/
/renders/889900/frames/0004

THANK YOU! 谢谢!

Instead of thinking about your api in terms of URLs, try thinking of it more like pages and links 与其以URL来思考您的api,不如尝试以页面和链接的形式来思考它。

between those pages. 在这些页面之间。

Consider the following: 考虑以下:

替代文字

Will it be reasonable to create a resource for users? 为用户创建资源是否合理? Do you have 10, 20 or 50 users? 您有10、20或50个用户吗? Or do you have 10,000 users? 还是您有10,000个用户? If it is the latter then obviously creating a single resource that represents all users is probably not going too work to well when you do a GET on it. 如果是后者,那么显然,当您对它执行GET时,创建一个代表所有用户的单一资源可能不会很好地工作。

Is the list of Users a reasonable root url? 用户列表是否是合理的根URL? ie The entry point into your service. 即进入服务的入口。 Should the list of projects that belong to a GraphicsCompany be a separate resource, or should it just be embedded into the Graphics Company resource? 属于GraphicsCompany的项目列表应该是单独的资源,还是应该仅嵌入到Graphics Company资源中? You can ask the same question of each of the 1-to-many relationships that exist. 您可以对存在的每个一对多关系询问相同的问题。 Even if you do decide to merge the list of projects into the GraphicsCompany resource, you may still want a distinct resource to exist simple for the purpose of being able to POST to it in order to create a new project for that company. 即使您决定将项目列表合并到GraphicsCompany资源中,您仍可能希望存在一个简单的独特资源,以便能够对其进行POST,以便为该公司创建新项目。

Using this approach you should be able get a good idea of most of the resources in your API and how they are connected without having to worry about what your URLs look like. 使用这种方法,您应该能够很好地了解API中的大多数资源及其连接方式,而不必担心URL的外观。 In fact if you do the design right, then any client application you right will not need to know anything about the URLs that you create. 实际上,如果您进行正确的设计,那么您所使用的任何客户端应用程序将不需要了解有关您创建的URL的任何信息。 The only part of the system that cares what the URL looks like is your server, so that it can dispatch the request to the right controller. 系统中唯一关心URL外观的部分是您的服务器,以便它可以将请求分派给正确的控制器。

The other significant question you need to ask yourself is what media type are you going to use for these resources. 您需要问自己的另一个重要问题是,这些资源将使用哪种媒体类型。 How many different clients will need to access these resources? 有多少不同的客户端需要访问这些资源? Are you writing the clients, or is someone else? 您在写客户,还是其他人? Should you attempt to reuse an existing standard like XHTML and classes/microformats? 您是否应该尝试重用现有的标准,例如XHTML和类/微格式? Could you squeeze most of the information into Atom? 您能否将大多数信息压缩到Atom中? Maybe Atom with some extra namespaces like GDATA does it? 也许Atom有一些额外的名称空间,例如GDATA,对吗? Or is this only going to be used internally so you can just create your own media types, like application/vnd.YourCompany.Project+xml, application/vnd.YourCompany.Render+xml, etc. 或者这仅在内部使用,因此您可以创建自己的媒体类型,例如application / vnd.YourCompany.Project + xml,application / vnd.YourCompany.Render + xml等。

There are many things to think about when designing a REST api, don't get hung up on what your URLs look like and you should really try to avoid doing "design by URL". 在设计REST api时,有很多事情要考虑,不要挂在URL的外观上,而您应该真正避免做“按URL设计”。

Presuming that you authenticate to the service, I would use the 1st option, but remove the user, particularly if the user is the currently logged in user. 假设您对服务进行了身份验证,我将使用1st选项,但是删除用户,特别是如果该用户是当前登录的用户。

If user actually represents something else (like client), I would include it, but not if it simply designates the currently logged in user. 如果用户实际上代表其他东西(例如客户端),我将包括它,但如果它只是指定当前登录的用户,则不包括在内。 Agree with StaxMan, though, don't worry too much about squeezing the paths, as readability is key in RESTful APIs. 不过,与StaxMan达成共识,不必担心压缩路径,因为可读性是RESTful API的关键。

Personally I would not try to squeeze path too much, that is, some amount of redundant information is helpful both to quickly see what resource is, and for future expansion. 就我个人而言,我不会尝试过多压缩路径,也就是说,一定数量的冗余信息对于快速了解什么是资源以及对将来的扩展都是有帮助的。 Generally users won't be typing paths anyway, so verbosity is not all that bad. 通常,用户无论如何都不会键入路径,因此冗长程度并不是那么糟糕。

声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.

 
粤ICP备18138465号  © 2020-2024 STACKOOM.COM